Skip to content

Localization

Localization enables translating extension to different languages.

If the extension supports multiple languages, you can customize extension localization by specifying two build keys: locales_dir and locales_list.

Locales directory

locales_dir key specifies where in project directory to look for locales files. The default locales_dir is ./assets/locales/. If you prefer a different directory structure, override this default value.

Locales list

locales_list is an array that lists all supported languages, and such that the values of this array correspond to subdirectories under locales_dir. Only locales directories specified in this array will be included in the build, which allows excluding incomplete translations from build until they are ready to be included.

The default value of locales_list is ["en"].

Refer to this list of language codes when specifying value for this configuration.

You may split localization files into multiple .json files within the language-specific directory to improve maintainability. During builds all files within a language directory will be automatically combined into a single messages.json which is expected from a browser extensions.

Recommended reading: learn how to internationalize extensions.

Example

This configuration shows build configuration with custom path and multiple language outputs.

Build configuration

1
2
3
4
"xtbuild": {
  "locales_list": ["en","fr","pl"],
  "locales_dir": "./my/custom/locales/path/"
}

Corresponding project level file structure:

File Path Description
└ /my/custom/locales/path/ locales directory
        └─ en/messages.json English dictionary
        └─ fr/myFile.json French dictionary
        └─ pl/
                └─ app.json Polish dictionary, part 1
                └─ options.json Polish dictionary, part 2
        └─ de/messages.json German dictionary

Build behavior:

  • myFile.json will be renamed to messages.json
  • app.json and options.json will me concatenated and renamed to messages.json
  • extension will be available in 3 languages; dist/ directory will contain:
    • _locales/en/messages.json
    • _locales/fr/messages.json
    • _locales/pl/messages.json
  • German dictionary is excluded from build output because it is not included in locales_list