Firefox WebExtensions i18n: messages.json reference

The format is identical to Chrome

Firefox implements the WebExtension standard, which uses the same messages.json format Chrome pioneered. The folder structure, key schema, placeholder syntax, and default_locale rule are all identical:

my-addon/
├── manifest.json           ← "default_locale": "en" required
└── _locales/
    ├── en/
    │   └── messages.json
    ├── de/
    │   └── messages.json
    └── fr/
        └── messages.json

A messages.json file that works in Chrome will work in Firefox without modification. The only differences are in the runtime API name and a handful of AMO-specific considerations.

browser.i18n vs chrome.i18n

Firefox exposes the i18n API as browser.i18n. Chrome exposes it as chrome.i18n. The method signatures are identical — only the namespace differs:

// Chrome / Edge / Opera
chrome.i18n.getMessage("appName");
chrome.i18n.getMessage("welcomeMessage", ["Alice"]);
chrome.i18n.getUILanguage();

// Firefox / Safari
browser.i18n.getMessage("appName");
browser.i18n.getMessage("welcomeMessage", ["Alice"]);
browser.i18n.getUILanguage();

If you want a single codebase that works across Chrome and Firefox, the safest approach is to use chrome.i18n everywhere — Firefox supports it, and it avoids a runtime polyfill. Alternatively, use a compatibility shim:

// i18n.js — cross-browser shim
const i18n = (typeof browser !== "undefined" ? browser : chrome).i18n;

export function t(key, substitutions) {
  return i18n.getMessage(key, substitutions);
}

messages.json format reference

Firefox supports all three fields of the WebExtension message schema:

{
  "appName": {
    "message": "My Add-on",
    "description": "Name of the add-on shown in Firefox toolbar and AMO listing."
  },
  "notificationText": {
    "message": "New message from $SENDER$",
    "description": "Push notification text shown when a new message arrives.",
    "placeholders": {
      "sender": {
        "content": "$1",
        "example": "Alice"
      }
    }
  },
  "itemCount": {
    "message": "$COUNT$ items saved",
    "description": "Status bar label showing how many items are saved.",
    "placeholders": {
      "count": {
        "content": "$1",
        "example": "12"
      }
    }
  }
}

Using __MSG_key__ in manifest.json

The __MSG_key__ substitution syntax works the same way in Firefox as in Chrome. Firefox reads the active locale’s messages.json and substitutes the token before the manifest is evaluated:

{
  "manifest_version": 2,
  "name": "__MSG_appName__",
  "description": "__MSG_appDescription__",
  "default_locale": "en",
  "version": "1.0.0"
}

AMO localization behaviour

When you submit an add-on to AMO, the store uses your _locales/ folder in two ways:

Firefox locale codes

Firefox uses the same locale code format as Chrome — lowercase language code, optional underscore-separated region code — but the approved list is slightly different. The most important differences:

In practice, if you are targeting the major languages (top 20–30 locales), the codes are identical between Chrome and Firefox. Differences only appear for smaller regional languages.

Testing Firefox add-on i18n locally

The cleanest way to test a different locale in Firefox is web-ext, Mozilla’s official CLI tool for add-on development. Pass --start-url along with a Firefox profile set to the target locale, or use the --pref flag:

# Install web-ext globally
npm install -g web-ext

# Run with German locale
web-ext run --pref intl.locale.requested=de

# Run with Japanese locale
web-ext run --pref intl.locale.requested=ja

Alternatively, change the locale in Firefox directly:

# 1. Go to about:config in Firefox
# 2. Search for: intl.locale.requested
# 3. Set the value to your target locale code, e.g. "de" or "ja"
# 4. Restart Firefox
# 5. Reload your extension from about:debugging

Common Firefox-specific pitfalls

Cross-browser compatibility summary