JSON - Browser Extension

File format value

browser-extension-json

Copy value

List of supported file formats

The browser extension JSON format is the standard localization format used by browser extensions for Chrome, Firefox, Edge and Safari. Each extension stores translations in messages.json files within _locales/{lang}/ directories.

For more information about the format and how to use it, see the official i18n API documentation of the respective browser:

• Chrome Extensions
• Firefox WebExtensions
• Safari Extensions

Format details

File format example

{
  "appName": {
    "message": "My Extension",
    "description": "The name of the extension"
  },
  "appDescription": {
    "message": "A useful browser extension.",
    "description": "The description of the extension"
  },
  "buttonSave": {
    "message": "Save"
  }
}

Each top-level key is a message name (translation key). The value is an object with:

• message - the translated text (required)
• description - a note for translators (optional)
• placeholders - named placeholders used in the message (optional)

Placeholders

You can use named placeholders in the message field. Placeholder names are wrapped with $ signs.

{
  "greeting": {
    "message": "Hello, $USER$! You have $COUNT$ new messages.",
    "description": "Greets the user and shows the number of new messages",
    "placeholders": {
      "user": {
        "content": "$1",
        "example": "John"
      },
      "count": {
        "content": "$2",
        "example": "5"
      }
    }
  }
}

File structure

Browser extensions use the following directory structure for localization:

my-extension/
├── manifest.json
├── _locales/
│   ├── en/
│   │   └── messages.json
│   ├── pl/
│   │   └── messages.json
│   ├── de/
│   │   └── messages.json
│   └── es/
│       └── messages.json

The default_locale field in manifest.json should point to the default language:

{
  "name": "__MSG_appName__",
  "description": "__MSG_appDescription__",
  "default_locale": "en"
}

Upload translation files

Uploading English translations with descriptions to SimpleLocalize using CLI. Descriptions are read from the file automatically whenever present, and no upload option is needed to include them:

simplelocalize upload --apiKey <PROJECT_API_KEY> \
  --uploadFormat browser-extension-json \
  --uploadLanguageKey en \
  --uploadPath ./_locales/en/messages.json

By default, a description uploaded from the CLI is saved as the code description. It won't overwrite a description a translator has written manually in the Translation Editor. If you'd rather have the upload write straight into the translator-facing description instead, add the UPDATE_DESCRIPTIONS upload option:

simplelocalize upload --apiKey <PROJECT_API_KEY> \
  --uploadFormat browser-extension-json \
  --uploadLanguageKey en \
  --uploadPath ./_locales/en/messages.json \
  --uploadOptions UPDATE_DESCRIPTIONS

Learn more about uploading translations with CLI and about code vs. translator descriptions.

Download translation files

Downloading Polish, German and Spanish translations from SimpleLocalize using CLI:

simplelocalize download --apiKey <PROJECT_API_KEY> \
  --downloadFormat browser-extension-json \
  --downloadLanguageKey pl,de,es \
  --downloadPath ./_locales/{lang}/messages.json

Optionally, you can include descriptions in the downloaded files with the INCLUDE_DESCRIPTIONS option:

simplelocalize download --apiKey <PROJECT_API_KEY> \
  --downloadFormat browser-extension-json \
  --downloadLanguageKey pl,de,es \
  --downloadPath ./_locales/{lang}/messages.json \
  --downloadOptions INCLUDE_DESCRIPTIONS

By default INCLUDE_DESCRIPTIONS exports the translator description. If you want to export the code description instead, to get back exactly what was uploaded from your codebase, without depending on whether a translator has since added their own note — combine it with USE_CODE_DESCRIPTIONS:

simplelocalize download --apiKey <PROJECT_API_KEY> \
  --downloadFormat browser-extension-json \
  --downloadPath ./en/messages.json \
  --downloadLanguageKey en \
  --downloadOptions INCLUDE_DESCRIPTIONS,USE_CODE_DESCRIPTIONS

Descriptions are stored per translation key, not per language, so the same description is exported regardless of which language you download.

Learn more about downloading translations with CLI and about code vs. translator descriptions.