Skip to main content
Extension.js discovers locale files next to your manifest and validates that each declared locale has a messages.json. It emits locale JSON assets into the browser-specific build. Extension.js picks up edits to any locale file in dev without a full restart.

​
Template example

​
action-locales

action-locales template screenshot See localized extension metadata and UI strings with _locales support. 
npx extension@latest create my-extension --template=action-locales
Repository: extension-js/examples/action-locales

​
Locale capabilities

CapabilityWhat it gives you
Locale discoveryDetect _locales/<locale>/messages.json from manifest location
ValidationCatch missing default locale files and unresolved __MSG_*__ keys
Build output mappingEmit locale files in the expected extension output structure
Dev watch supportReload on locale file changes during development

​
Expected structure

manifest.json
_locales/
  en/
    messages.json
  fr/
    messages.json
default_locale in manifest.json should map to an existing _locales/<default>/messages.json.

​
Sample locales declaration in manifest.json

Here is how to declare locales in manifest.json: 
{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.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

Example messages.json file for translations: 
{
  "extension_name": {
    "message": "My Extension"
  },
  "extension_description": {
    "message": "This is a localized description of my extension."
  }
}

​
Output path

Extension.js emits locale JSON files under: 
_locales/<locale>/messages.json

​
Development behavior

  • Extension.js adds locale JSON files to compilation dependencies and watches them.
  • Locale changes trigger extension reload behavior (hard reload), not component-style hot module replacement (HMR).
  • Extension.js fails validation with actionable diagnostics when required locale files are missing or invalid.

​
Validation behavior

Extension.js validates:
  • default_locale presence when the project uses _locales
  • existence of _locales/<default>/messages.json
  • JSON validity for locale files
  • __MSG_*__ references in manifest against default locale keys

​
Troubleshooting missing locale keys

If your manifest uses __MSG_extension_description__, ensure the default locale file contains extension_description: 
{
  "extension_description": {
    "message": "Localized extension description"
  }
}
If the default locale does not define the key, build/validation diagnostics surface the mismatch.

​
Best practices

  • Keep messages.json keys consistent across locales.
  • Update default locale first, then propagate keys to other locales.
  • Validate locale JSON in CI to catch malformed files before packaging.
  • Keep locale files close to manifest (manifestDir/_locales) for predictable resolution.

​
Next steps