Locales and internationalization

​

Template example

​

action-locales

npx extension@latest create my-extension --template=action-locales

pnpx extension@latest create my-extension --template=action-locales

yarn dlx extension@latest create my-extension --template=action-locales

bunx extension@latest create my-extension --template=action-locales

deno run -A npm:extension@latest create my-extension --template=action-locales

​

Locale capabilities

​

Expected structure

manifest.json
_locales/
  en/
    messages.json
  fr/
    messages.json

​

Sample locales declaration in manifest.json

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

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

​

Sample messages.json file

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

​

Output path

_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

• 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

{
  "extension_description": {
    "message": "Localized extension description"
  }
}

​

Best practices

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

​

Next steps

• Understand update outcomes in dev update behavior.
• Continue with JSON in development.
• Learn about manifest development behavior.