__MSG_key__ in manifest.json explained

What __MSG_key__ does

When Chrome or Firefox reads manifest.json, it scans string values for tokens matching the pattern __MSG_key__ — two underscores, the word MSG, an underscore, the key name, then two more underscores. For each token it finds, it looks up key in the active locale’s messages.json file and replaces the token with the message value. This happens at manifest parse time — before any JavaScript runs.

// manifest.json
{
  "manifest_version": 3,
  "name": "__MSG_appName__",
  "description": "__MSG_appDescription__",
  "default_locale": "en",
  "version": "1.0.0",
  "action": {
    "default_title": "__MSG_actionTitle__",
    "default_popup": "popup.html"
  }
}

// _locales/en/messages.json
{
  "appName":        { "message": "Tab Manager Pro" },
  "appDescription": { "message": "Organize your browser tabs with one click." },
  "actionTitle":    { "message": "Open Tab Manager" }
}

// _locales/de/messages.json
{
  "appName":        { "message": "Tab Manager Pro" },
  "appDescription": { "message": "Organisiere deine Browser-Tabs mit einem Klick." },
  "actionTitle":    { "message": "Tab-Manager öffnen" }
}

For a German-language user, Chrome reads _locales/de/messages.json and resolves the manifest as if it were written:

{
  "name": "Tab Manager Pro",
  "description": "Organisiere deine Browser-Tabs mit einem Klick.",
  "action": { "default_title": "Tab-Manager öffnen" }
}

Which manifest fields support __MSG_key__

Not every manifest field accepts the token. Chrome only substitutes __MSG_key__ in fields that it treats as user-visible strings. Using the token in an unsupported field causes it to be treated as a literal string — it will appear exactly as __MSG_key__ in the UI.

In practice, most developers only use __MSG_ for name and description — the two fields that appear in both the browser toolbar and the store listing.

How Chrome resolves the active locale

Chrome determines which messages.json to use by checking the user’s browser UI language against your available _locales folders, following a three-step fallback:

1. 1Look for the exact locale match: _locales/de_AT/messages.json for an Austrian German user.
2. 2If not found, try the parent language: _locales/de/messages.json.
3. 3If still not found, fall back to _locales/{default_locale}/messages.json.

This fallback applies to __MSG_key__ tokens in the manifest the same way it applies to chrome.i18n.getMessage() calls in JavaScript. See the complete Chrome extension localization guide for the full setup walkthrough.

The connection to the Chrome Web Store listing

This is one of the most valuable but least understood aspects of __MSG_key__: the Chrome Web Store reads your manifest and uses the resolved name and description values to display your extension to store visitors in their language.

Concretely: if you have a _locales/de/messages.json with a German appDescription, a German-speaking user browsing the Chrome Web Store sees your extension description in German — automatically, without you entering anything in the Chrome Developer Dashboard.

Firefox AMO works the same way: it resolves __MSG_appName__ and __MSG_appDescription__ from your messages.json files and displays the localized text on the add-on listing page for visitors in matching locales.

Common pitfalls

// ✗ manifest references appName, but it's missing from the source file
// _locales/en/messages.json
{ "appDescription": { "message": "..." } }  // ← appName is missing

// ✓ add the missing key
{ "appName": { "message": "My Extension" }, "appDescription": { "message": "..." } }

// ✗ typo — token is __MSG_appame__ (missing N)
"name": "__MSG_appame__"

// ✓ matches the key exactly
"name": "__MSG_appName__"

// ✗ version does not support __MSG_ substitution
"version": "__MSG_version__"   ← fails manifest validation

// ✓ version must be a literal semver string
"version": "1.0.0"

<!-- ✗ does NOT work in HTML — renders as literal text -->
<h1>__MSG_appName__</h1>

<!-- ✓ set text content from JS instead -->
<h1 id="title"></h1>
<script>
  document.getElementById("title").textContent =
    chrome.i18n.getMessage("appName");
</script>

// ✗ always shows English, ignores translations
"name": "Tab Manager Pro"

// ✓ resolves from messages.json for each user's locale
"name": "__MSG_appName__"

Minimal working example

Here is the smallest possible extension that uses __MSG_key__ correctly, with English and German locales:

// manifest.json
{
  "manifest_version": 3,
  "name": "__MSG_appName__",
  "description": "__MSG_appDescription__",
  "default_locale": "en",
  "version": "1.0.0"
}

// _locales/en/messages.json
{
  "appName": {
    "message": "My Extension",
    "description": "The extension name shown in the toolbar and Chrome Web Store."
  },
  "appDescription": {
    "message": "A short description of what my extension does.",
    "description": "Short store listing description. Max 132 characters."
  }
}

// _locales/de/messages.json
{
  "appName": {
    "message": "Meine Erweiterung",
    "description": "The extension name shown in the toolbar and Chrome Web Store."
  },
  "appDescription": {
    "message": "Eine kurze Beschreibung meiner Erweiterung.",
    "description": "Short store listing description. Max 132 characters."
  }
}

With this setup, German-language users see “Meine Erweiterung” in the Chrome toolbar, in the extension management page at chrome://extensions, and in the Chrome Web Store listing — all from those two keys in messages.json.

Validating __MSG_key__ references before uploading

The Chrome Web Store validates all __MSG_key__ references on upload and rejects any ZIP where a referenced key is missing from the default_locale file. You can catch this locally before uploading with a short script — the same one from the messages.json validation guide:

// validate-manifest-keys.mjs
import { readFileSync } from "node:fs";
import { join } from "node:path";

const manifest = JSON.parse(readFileSync("manifest.json", "utf8"));
const defaultLocale = manifest.default_locale;

if (!defaultLocale) process.exit(0);

const sourceKeys = new Set(
  Object.keys(JSON.parse(readFileSync(join("_locales", defaultLocale, "messages.json"), "utf8")))
);

const manifestStr = JSON.stringify(manifest);
const MSG_RE = /__MSG_([A-Za-z0-9_@]+)__/g;
let hasErrors = false;

for (const [, key] of manifestStr.matchAll(MSG_RE)) {
  if (!sourceKeys.has(key)) {
    console.error(`manifest.json: __MSG_${key}__ not found in ${defaultLocale}/messages.json`);
    hasErrors = true;
  }
}

if (hasErrors) process.exit(1);
else console.log("All manifest __MSG_ references valid ✓");

See default_locale rules and common errors for the full list of manifest validation errors Chrome and the Web Store enforce.

Quick reference