> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Locales and internationalization

> Ship localized extension metadata and UI strings with _locales handling. Extension.js discovers, validates, and emits locale JSON for each build.

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. During development, it picks up edits to any locale file without a full restart.

## Template example

### `action-locales`

<img src="https://mintcdn.com/extensionjs/VCnDd7fX2Nza24SE/images/examples/action-locales/screenshot.png?fit=max&auto=format&n=VCnDd7fX2Nza24SE&q=85&s=a5bd1b1477de2d44b499d9a85e1426d3" alt="action-locales template screenshot" width="2400" height="1800" data-path="images/examples/action-locales/screenshot.png" />

See localized extension metadata and UI strings with `_locales` support.

<CodeGroup>
  ```bash npm theme={null}
  npx extension@latest create my-extension --template=action-locales
  ```

  ```bash pnpm theme={null}
  pnpx extension@latest create my-extension --template=action-locales
  ```

  ```bash yarn theme={null}
  yarn dlx extension@latest create my-extension --template=action-locales
  ```

  ```bash bun theme={null}
  bunx extension@latest create my-extension --template=action-locales
  ```

  ```bash deno theme={null}
  deno run -A npm:extension@latest create my-extension --template=action-locales
  ```
</CodeGroup>

Repository: [extension-js/examples/action-locales](https://github.com/extension-js/examples/tree/main/examples/action-locales)

## Locale capabilities

| Capability           | What it gives you                                                  |
| -------------------- | ------------------------------------------------------------------ |
| Locale discovery     | Detect `_locales/<locale>/messages.json` from manifest location    |
| Validation           | Catch missing default locale files and unresolved `__MSG_*__` keys |
| Build output mapping | Emit locale files in the expected extension output structure       |
| Dev watch support    | Reload on locale file changes during development                   |

## Expected structure

```plaintext theme={null}
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`:

```json theme={null}
{
  "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:

```plaintext theme={null}
_locales/
└── en/
    └── messages.json
```

## Sample `messages.json` file

Example `messages.json` file for translations:

```json theme={null}
{
  "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:

```plaintext theme={null}
_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`:

```json theme={null}
{
  "extension_description": {
    "message": "Localized extension description"
  }
}
```

If the default locale does not define the key, Extension.js surfaces a diagnostic explaining 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 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](/docs/workflows/dev-update-behavior).
* Continue with [JSON in development](/docs/implementation-guide/json).
* Learn about [manifest development behavior](/docs/implementation-guide/manifest-json).