JSON - Browser Extension | SimpleLocalize

File format value

browser-extension-json

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:

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:

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

Learn more about uploading translations with CLI.

Download translation files

Downloading Polish, German and Spanish translations with descriptions 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:

  --downloadFormat browser-extension-json \
  --downloadLanguageKey pl,de,es \
  --downloadPath ./_locales/{lang}/messages.json \
  --downloadOptions INCLUDE_DESCRIPTIONS

Learn more about downloading translations with CLI.