@msweb/i18n-webcomponents

v0.0.3

Published

5 months ago

An opinionated NPM package to handle i18n with web components

Downloads

0High
0Medium
0Low

manuelsanchezweb

boilerplate template typescript vscode jest husky commitizen semantic-release codecov

Basic Use

We can localize different languages easily by just creating a basic configuration. Create a file called i18n.config.ts (or .js) and write something like the following:

export const config = {
  defaultLanguage: 'en', // primary language until a cookie is set and if browser language is not available
  languages: ['en', 'es'], // languages that we want to consider in the app
  localesPath: './locales', // folder where we will store the translation files
  localesFormat: 'json', // the format of the translation ('json' and 'xml' are accepted)
};

Once you have this, we just import it to the main file.

import { type ConfigOptions, i18nService } from '@msweb/i18n-webcomponents';
import { config } from '../i18n.config';

i18nService.init(config as ConfigOptions)

[!IMPORTANT]
Files should be called [lang].json or [lang].xml. Since there are maybe some specifities specially for the xml structure, I would recommend to take a look to the locales examples in the repo.

Now, if we have for example en.json and es.json with the same key, let us say, greeting, we could do the following in our markup:

<f-translate key="greeting"></f-translate>

Switching Languages

As we said, the default language is cool, but we need a way of switching the language. We can do it through two different ways:

Either we add the functionality to any element using data-translate="[lang]"
Or we call the method i18nService.switchLanguage('[lang]') passing the locale we need.

<button data-translate="en">English</button>
<button data-translate="es">Spanish</button>

Nesting

This is specific for the ones using json format. It is possible to create nested structures with your json. The package will flatten the object and make the key coincide with what you have nested. But please, take in mind that everything will be transformed into kevab case>.

en.json
{
  "greeting": "Hello",
  "farewell": "Goodbye",
  "custom-greeting": "Hello, {name}",
  "coins": "You have {number} coins, {name}",
  "days": {
    "monday": "Monday",
    "lovely": {
      "tuesday": "Tuesday"
    }
  }
}

<f-translate key="days-monday"></f-translate>
<f-translate key="days-lovely-tuesday"></f-translate>

Interpolation

We will sometimes need to pass variables inside our translation files. That is pretty common, check for example in the above json example the custom-greeting or the coins. This can be done also if we are using xml.

<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en" datatype="plaintext" original="file">
    <body>
      <trans-unit id="greeting">
        <source>Hello</source>
        <target>Hello</target>
      </trans-unit>
      <trans-unit id="farewell">
        <source>Goodbye</source>
        <target>Goodbye</target>
      </trans-unit>
      <trans-unit id="custom-greeting">
        <source>Hello, {name}</source>
        <target>Hello, {name}</target>
      </trans-unit>
      <trans-unit id="coins">
        <source>You have {number} coins, {name}</source>
        <target>You have {number} coins, {name}</target>
      </trans-unit>
      <trans-unit id="days-monday">
        <source>Monday</source>
        <target>Monday</target>
      </trans-unit>
      <trans-unit id="days-lovely-tuesday">
        <source>Tuesday</source>
        <target>Tuesday</target>
      </trans-unit>
      <!-- ... additional trans-unit elements for other keys ... -->
    </body>
  </file>
</xliff>

Localizing Attributes

For accessibility and good practices reasons, we can also localize different attributes like aria-label or title. The way it is a bit different, we are passing props inside the attribute data-i18n.

<button data-i18n='{"aria-label": "days-monday"}'>Check day of the week</button>

And of course we can combine different tools from the package here. The following example makes no much sense, but I am pretty sure you can come up with something more useful than this:

<button
  class="cool-btn"
  data-translate="en"
  data-i18n='{"aria-label": "days-monday", "title": "days-lovely-tuesday"}'
>
  <f-translate key="greeting"></f-translate>
</button>

Error handling

I have tried to equip the npm with a good number of try/catch, with some cool ts types, but of course, I can imagine there will be some errors/bugs in the dev experience. Please, let me know so that I can update this part with some of the common issues.

Examples of use

I recommend to take a look to the following links for further and quicker development:

Contact

I have developed it solo with the help of Chat GPT and a cool starter repo for npm packages with TypeScript that I can only recommend. In case of some issues, please do not hesitate to contact me.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme