Themes
Extensions
Deploying your app
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.To create a new translation for your application
Instructions
Example
- 1.
- 2.
- 3.
- 4.Run the application in production or development mode at least once. This will create the translation files in
i18nfolder 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/scandipwaof version equal or higher than the4.0.1therefore, the@scandipwa/webpack-i18n-runtimeextension 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/scandipwais written in translatable fashion. Indeed, most files contain proper translations, in example:AddToCart. - 3.Let's add (enable) the
ru_RUlocale in thepackage.json's fieldscandipwa.localesas follows:1{2"scandipwa": {3"locales": {4"en_US": true,5"ru_RU": true6}7}8}Copied! - 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.jsonof our theme.
Installing the package
Heads up!
This internationalization mechanism is included into the
@scandipwa/scandipwa theme since version 4.0.1 and above. In case of custom project, you must install and enable it manually.To get this mechanism up and running, you need to:
​ Install the module
âš¡
1
# For yarn users
2
yarn add @scandipwa/webpack-i18n-runtime
3
​
4
# For npm users
5
npm i @scandipwa/webpack-i18n-runtime
Copied!
​Enable it as a
âš¡
scandipwa extension1
{
2
"scandipwa": {
3
"extensions": {
4
"@scandipwa/webpack-i18n-runtime": true
5
}
6
}
7
}
Copied!
Writing translatable code
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.
1
/** This is NOT translatable! */
2
render() {
3
return <p>My Account</p>
4
}
5
​
6
/** This is NOT translatable as well! */
7
render() {
8
return <p>{ 'My Account' }</p>
9
}
10
​
11
/** This IS translatable! */
12
render() {
13
return <p>{ __('My Account') }</p>
14
}
Copied!
Specifying the locales to compile
When invoking the compilation, you should specify the locales you are willing to compile in the
package.json file of your theme, as follows:1
{
2
"scandipwa": {
3
"locales": {
4
"en_US": true,
5
"fr_FR": true
6
}
7
}
8
}
Copied!
Creating translation files
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.Translation sources
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.Useful build-time information
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.parseable, 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.
How to enable the translations on my page
After installing the translations, please follow this guide to enable them.
Locale Options
User Manual
Heads up!
If you don't have a local backend and start frontend in normal mode, you should add
defaultLocale to your index.html file.1
<script>
2
window.defaultLocale = 'en_US';
3
</script>
Copied!