Internationalization
Internationalization - also known as "translation", "i18n" – is a process of making your application international.
The NPM package
@scandipwa/webpack-i18n-runtime
is responsible for this mechanics in the Create ScandiPWA App ecosystem.Instructions
Example
- 1.
- 2.
- 3.
- 4.Run the application in production or development mode at least once. This will create the translation files in
i18n
folder of your application. It will also warn you, if some translations are duplicated, invalid or missing. - 5.Propagate the internationalization files with proper translations. Some translations may already be present - parent themes and extensions can provide these values.
Let's assume we are also starting with blank repository, whose parent theme is
@scandipwa/scandipwa
. Let's assume we are using @scandipwa/scandipwa
of version 4.0.1
. - 1.We are using
@scandipwa/scandipwa
of version equal or higher than the4.0.1
therefore, the@scandipwa/webpack-i18n-runtime
extension is already installed and enabled. - 2.We did no modification to source code (our theme is blank), therefore we assume that the source code of
@scandipwa/scandipwa
is written in translatable fashion. Indeed, most files contain proper translations, in example:AddToCart
. - 3.Let's add (enable) the
ru_RU
locale in thepackage.json
's fieldscandipwa.locales
as follows:{"scandipwa": {"locales": {"en_US": true,"ru_RU": true}}} - 4.Let's run the application, it should warn us about all missing translations in case they present. Ideally there should be no invalid translations, but in case there are we should address them. This will not however break the application.
- 5.Now we can modify and add translations in
i18n/ru_RU.json
of our theme.
To get this mechanism up and running, you need to:
Install the module
⚡
# For yarn users
yarn add @scandipwa/webpack-i18n-runtime
# For npm users
npm i @scandipwa/webpack-i18n-runtime
Enable it as a
⚡
scandipwa
extension{
"scandipwa": {
"extensions": {
"@scandipwa/webpack-i18n-runtime": true
}
}
}
In the application, all the translatable strings should get wrapped into the
__(...)
translation function. Every string wrapped into this function will be available to translate inside of your translation files.The function is globally provided, you do not need to import it manually.
/** This is NOT translatable! */
render() {
return <p>My Account</p>
}
/** This is NOT translatable as well! */
render() {
return <p>{ 'My Account' }</p>
}
/** This IS translatable! */
render() {
return <p>{ __('My Account') }</p>
}
When invoking the compilation, you should specify the locales you are willing to compile in the
package.json
file of your theme, as follows:{
"scandipwa": {
"locales": {
"en_US": true,
"fr_FR": true
}
}
}
If a translation for the given locale is not found in your theme, it is automatically created as
./i18n/${locale}.json
during the build time.Then, it gets replenished with all the non-translated values from the compiled theme.
The default locale is
en_US
. No translation files will be automatically generated for this locale. You may create a translation file for the default locale manually, usually, it is not necessary.During the compilation time, the translations are collected from several sources and merged together. A chunk is generated for each locale code.
If the same string is translated in multiple translation files, the ones with higher position (from listed below) overwrite the ones with lower position. Exception for this rule: falsy (e.g,
null
, undefined
, ""
) values can be overwritten even from a file with lower priority.The order is as follows:
- 1.Child theme
- 2.Parent themes from youngest (e.g. father) to the oldest (e.g. grandfather)
- 3.Extensions
Translations in extensions - it is allowed (and, in most cases, necessary) to have translations inside of extensions. To do that, you need to put a translation file for your extension into that extension's
i18n/${locale}.json
file.After a successful compilation, you will be presented with any information on the following matters:
- 1.Unused translations - it is not recommended polluting your translation files with unused translations, this plugin will point out any translation strings in your theme that are not used in the application. It is recommended to remove them. You will not be see such information about your plugins or parent themes.
- 2.Missing translations - if your application lacks any translations, you are going to be warned about it. You will be provided this information about your theme only.
- 3.Corrupted translation files - if any of your files are corrupted, i.e. not
JSON.parse
able, you are going to be warned about it as well. - 4.Overwriting falsy value by translation with lower priority - e.g. if your theme's translation file contains
"Account": null
(any falsy value, not only null) and some parent theme or extension's one contains"Account": "Compte"
, the second one will be taken (even though the priority is lower for that one) and you will get alarmed about it.
After installing the translations, please follow this guide to enable them.
<script>
window.defaultLocale = 'en_US';
</script>