messages.json format explained (with placeholders)

File location

Each locale gets its own messages.json file inside a _locales folder in the extension root:

my-extension/
├── manifest.json
├── _locales/
│   ├── en/
│   │   └── messages.json   ← default locale
│   ├── de/
│   │   └── messages.json
│   ├── fr/
│   │   └── messages.json
│   └── ja/
│       └── messages.json
└── ...

The default_locale field in manifest.json tells the browser which folder is the fallback when a user’s locale is not available:

{
  "manifest_version": 3,
  "name": "__MSG_appName__",
  "default_locale": "en",
  ...
}

The three fields of a message entry

Each key in messages.json maps to an object with up to three fields:

{
  "appName": {
    "message": "My Extension",
    "description": "The name of the extension shown in the browser UI.",
    "placeholders": {}
  }
}

Placeholders: $PLACEHOLDER$ syntax

When a string contains dynamic values — a user name, a count, a URL — you define them as placeholders rather than embedding them literally. This prevents the AI (or human translator) from accidentally altering the variable name.

{
  "welcomeMessage": {
    "message": "Welcome, $USER$! You have $COUNT$ new messages.",
    "description": "Greeting shown on the dashboard after login.",
    "placeholders": {
      "user": {
        "content": "$1",
        "example": "Alice"
      },
      "count": {
        "content": "$2",
        "example": "3"
      }
    }
  }
}

The key rules for placeholder names:

• •In the message string, placeholders are referenced as $NAME$ — always uppercase with dollar signs on both sides.
• •In the placeholders object, the key is the same name but lowercase (e.g. user for $USER$).
• •The content field specifies how the placeholder value is supplied at runtime: $1 means the first argument to getMessage(), $2 the second, and so on (up to $9).
• •The example field is optional but helps translators understand what the placeholder represents.

Calling getMessage() with substitutions

Pass substitution values as the second argument to chrome.i18n.getMessage() (or browser.i18n.getMessage() in Firefox/Safari). The second argument is an array of strings mapped to $1, $2, etc.:

// Chrome / Edge / Opera
const msg = chrome.i18n.getMessage("welcomeMessage", ["Alice", "3"]);
// → "Welcome, Alice! You have 3 new messages."

// Firefox / Safari
const msg = browser.i18n.getMessage("welcomeMessage", ["Alice", "3"]);
// → "Welcome, Alice! You have 3 new messages."

Placeholders without positional substitution

Sometimes the placeholder value is a literal string that never changes — for example, a brand name or URL you want to keep in every locale. Set content to the literal string instead of $1:

{
  "openDashboard": {
    "message": "Open $PRODUCT_NAME$ dashboard",
    "description": "Button label for the main dashboard link.",
    "placeholders": {
      "product_name": {
        "content": "LocalePack"
      }
    }
  }
}

In this case getMessage("openDashboard") returns "Open LocalePack dashboard" — no substitution array needed. The brand name is baked in and safe from translation.

Common mistakes

Full example: a complete messages.json

{
  "appName": {
    "message": "My Extension",
    "description": "The name of the extension shown in browser UI and the Web Store."
  },
  "appDescription": {
    "message": "Boost your productivity with one click.",
    "description": "Short description shown in browser UI and Web Store listings."
  },
  "welcomeMessage": {
    "message": "Welcome, $USER$!",
    "description": "Greeting shown after the user signs in.",
    "placeholders": {
      "user": {
        "content": "$1",
        "example": "Alice"
      }
    }
  },
  "itemCount": {
    "message": "You have $COUNT$ items in your list.",
    "description": "Status message showing how many items the user has saved.",
    "placeholders": {
      "count": {
        "content": "$1",
        "example": "5"
      }
    }
  },
  "openDocs": {
    "message": "Open $PRODUCT$ documentation",
    "description": "Link label for the documentation page.",
    "placeholders": {
      "product": {
        "content": "My Extension"
      }
    }
  }
}