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

  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.

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:

# For yarn users
yarn add @scandipwa/webpack-i18n-runtime

# For npm users
npm i @scandipwa/webpack-i18n-runtime
{
    "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.

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>

Last updated