i18n-react-loader

Installation

  npm install --save-dev i18n-react-loader

Setup

There are two different use cases for this module. The first is to utilize a server to retrieve the localization files. The second option is to have the project this library is being implemented within handle providing the translation data (in this case, the library is far less useful...).

This requires a server that responds with JSON to the following requests (response format example below):

Server-side Handling

The first request to {URL}/i18n/locales is to retrieve a list of supported locales. Each locale is defined as an object, containing a key, label, and code. Note that the code is that of the browser locale (see http://www.metamodpro.com/browser-language-codes for list).

Server Endpoints Needed

Request

  GET {URL}/i18n/locales

Response

  [
    { key: 'en', label: 'English', code: 'en-US' },
    { key: 'sp', label: 'Espanol', code: 'es-MX' },
  ]

The second request the server needs to support is to retrieve the individual locale mappings.

Request

  GET {URL}/i18n/locales/{key}

Response

  {
    "welcome": {
      "hello": "Hello, {name}",
      "intro": "This is an example application.",
      "locales": {
        "0": "{context} locales",
        "1": "{context} locale",
        "2..20": "{context} locales",
        "_": "A LOT of locales"
      },
      "registeredText": "There has been {{welcome.locales}} registered to this day."
    }
  }

Initialization of library

index.js (app entry)

  Translator.init({
    useExternalAPI: true,
    apiURL: `{SERVER_URL}/i18n/locales`,
    defaultLocale: 'en', // key for default locale
  }).then(() => {
    // Render your app -- React.render(...);
  });

app.js (main component)

The most important thing here is to note that you must set a key on the app container in order for it to force a re-render when the locale changes.

The changeLocale(localeKey) function shows how you change the locale. There's not much to it.

  ...

  changeLocale(localeKey) {
    if (this.state.localeKey !== localeKey) {
      Translator.setLocale(localeKey)
        .then(() => {
          this.setState({ localeKey });
        });
    }
  }

  ...

  render() {
    ...

    return (
      <div key={this.state.localeKey}>
        ... your app template ...
      </div>
    );
  }

Local Project Handling

The only difference between Local and Server handling is how you initialize the library (index.js example above). For local handling, it is necessary to build a map of all your localization data and pass it in. This likely is not ideal and could definitely be optimized, but it was not the main concern when writing this library. I ran into issues trying to let the library read external files containing the data due to it being ran in the browser (no access to the file system).

  Translator.init({
    useExternalAPI: false,
    defaultLocale: 'en', // key for default locale
    localSupportedLocales: require('./resources/mock-data').LOCALES,
    localLocaleMap: {
      en: require('./locales/en.json'),
      sp: require('./locales/sp.json'),
    },
  }).then(() => {
    // Render your app -- React.render(...);
  });

localSupportedLocales: This should match the format of what the endpoint listed above would return (an array

of objects).

localLocaleMap: This is a key-value map containing all of the translations. The top level map keys are the

locale keys ('en', 'sp', etc). The values are maps of all the translations (see the response of the 2nd endpoint above).

A full example would look like this:

{
  en: {
    welcome: {
      hello: "Hello, {name}",
      intro: "This is an example application.",
      locales: {
        0: "{context} locales",
        1: "{context} locale",
        2..20: "{context} locales",
        _: "A LOT of locales"
      },
      registeredText: "There has been {{welcome.locales}} registered to this day."
    }
  }
}

Notes

This library was developed to meet the needs of our project for handling of translations from an external server. The i18n-react library did not have any functionality to handle this, we we build this little lib to do so. I quickly threw in the ability to support local locale files, but it's not pretty. Feel free to improve upon it and create a PR!

License

ISC