Provides i18n-react the ability to load translations from a server or a provided map
npm install i18n-react-loader
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):
$3
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: ,
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 (
... your app template ...
);
}
$3
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!