Locales#

Locales allow browser extensions to support multiple languages and enhancing the user experience. Extension.js handles locales defined in your manifest.json as the browser would, and ensures that they are emitted and included in the output directory, making them accessible during runtime.

Locales File Support#

Extension.js offers robust support for locales, ensuring that all defined translations are correctly emitted and watched for changes. The following manifest fields are used for declaring locales:

Sample Locales Declaration in manifest.json#

Here’s how to declare locales in your manifest.json:

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "default_locale": "en",
  "description": "__MSG_extension_description__"
}

You would then include JSON files for each locale inside the _locales folder:

_locales/
└── en/
    └── messages.json

Sample messages.json File#

Here’s an example of a messages.json file used for translations:

{
  "extension_name": {
    "message": "My Extension"
  },
  "extension_description": {
    "message": "This is a localized description of my extension."
  }
}

Output Path#

The output path for locale files will follow the structure defined by the _locales folder. The resulting files will look like this:

dist/
└── _locales/
    ├── en/
    │   └── messages.json
    └── fr/
        └── messages.json

How Extension.js Handles Locales#

The plugin responsible for handling locale files in Extension.js ensures the following steps occur during compilation:

1. Emit Locale Files: Locale files declared in the manifest.json are emitted to the output directory.
2. Add to File Dependencies: Locale files are added to the file dependencies of the compilation, ensuring any updates trigger a rebuild.
3. Support for Multiple Languages: Support for multiple languages through the _locales folder is provided.
4. Error Handling: Warnings are generated if locale files are missing or incorrectly configured during the build process.

Best Practices#

• Use the _locales folder to organize translations for different languages.
• Always declare your default_locale in the manifest.json to ensure proper localization support.
• Ensure that your locale JSON files are well-formed and contain all necessary translations.

Next Steps#

• Learn more about handling locale files and other static assets via Special Folders.