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

1. Make sure the @scandipwa/webpack-i18n-runtime is installed and enabled by following this guide.

2. Make sure your code is translatable, follow the "Writing translatable code" guide.

3. Propagate the field scandipwa.locales in package.json with desired locales to compile.

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.

Example

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 the 4.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 the package.json's field scandipwa.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.

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

# 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
        }
    }
}

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.

    /** 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>
    }

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:

{
    "scandipwa": {
        "locales": {
            "en_US": true,
            "fr_FR": true
        }
    }
}

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 OptionsUser 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.

<script>
  window.defaultLocale = 'en_US';
</script>