Plasmo i18n: the locales/ folder gotcha

Plasmo does not read _locales/ at the project root

Note what is not in that list: a bare _locales/ at the project root. That path is where the built extension carries its catalogues — Plasmo generates it for you during the build. Putting source files there yourself puts them somewhere the build never looks.

Why unzipping a _locales ZIP at the root does nothing

Every messages.json translation service — LocalePack included — hands you a _locales.zip containing a _locales/ directory. That shape is correct for a plain extension, where you drop it next to manifest.json and are done. In Plasmo, extracting it at the project root produces a directory the bundler ignores.

What you get if you unzip at the root — nothing happens:

my-plasmo-extension/
├── _locales/              ← ignored by Plasmo
│   ├── de/
│   │   └── messages.json
│   ├── en/
│   │   └── messages.json
│   └── fr/
│       └── messages.json
├── package.json
├── popup.tsx
└── tsconfig.json

What it should look like — extract the ZIP’s contents into locales/:

my-plasmo-extension/
├── locales/               ← Plasmo reads this
│   ├── de/
│   │   └── messages.json
│   ├── en/
│   │   └── messages.json
│   └── fr/
│       └── messages.json
├── package.json
├── popup.tsx
└── tsconfig.json

Or, if you prefer the underscore convention, under assets/:

my-plasmo-extension/
├── assets/
│   └── _locales/          ← also read by Plasmo
│       ├── de/
│       │   └── messages.json
│       ├── en/
│       │   └── messages.json
│       └── fr/
│           └── messages.json
├── package.json
└── popup.tsx

The per-locale folder names are unchanged in every case — they are still Chrome _locales codes with underscores, such as pt_BR and zh_CN. Only the parent directory moves. See the _locales structure guide for the full list of valid codes.

default_locale lives in package.json

The second thing that trips people up: there is no manifest.json to edit. Plasmo generates the manifest, and manifest fields are declared in package.json under the manifest key.

{
  "manifest": {
    "default_locale": "en"
  }
}

Everything you know about default_locale from plain extension development still applies to the generated manifest — it is the same field, just declared somewhere else. If you have not hit its validation rules before, they are catalogued in default_locale: rules and common errors.

The alphabetical-default trap

This one is genuinely dangerous, because it fails silently and only in production. The Plasmo documentation states it plainly:

“By default, Plasmo picks the first locale alphabetically available as default.”

So if you omit default_locale and your project ships Arabic and English, the default locale becomes ar — not because anyone chose it, but because ar sorts before en.

locales/
├── ar/                    ← becomes default_locale if you omit the field
│   └── messages.json
├── de/
│   └── messages.json
└── en/                    ← what you almost certainly wanted
    └── messages.json

You will not notice this in local development if your browser is set to English: Chrome finds _locales/en/ and never needs the fallback. The default locale only surfaces for users whose language you did not translate — who then see Arabic instead of English.

Runtime: plain chrome.i18n, no wrapper

Plasmo does not ship an i18n helper. You call the WebExtension API directly:

chrome.i18n.getMessage("popup")

Because there is no wrapper, every standard behaviour of the API applies unchanged:

• •getMessage() is synchronous and returns a string. No await, no callback.
• •A missing message is not an error. Verbatim from the Chrome documentation: “If the message is missing, this method returns an empty string (‘’).” That is why a misplaced locales/ folder shows up as blank UI rather than a thrown exception.
• •getMessage() returns undefined if messageName is not a string, or if there are more than 9 substitutions.
• •Unsupported locale folders are skipped rather than rejected. Verbatim: “If you use an unsupported locale, Google Chrome ignores it.”

The practical consequence of the first two points together: there is no error anywhere in the pipeline that tells you the locale files are in the wrong place. The build succeeds, the API returns strings, and the strings happen to be empty.

The dev-server watching caveat

Locale files are watched by the dev server only if they existed before the dev server started. Create a new locale folder while plasmo dev is running and nothing will pick it up.

# Adding a locale while the dev server is running:
#   1. stop the dev server
#   2. create locales/fr/messages.json
#   3. start the dev server again

plasmo dev

This matters most right after you drop in a translated _locales ZIP: you have just created a dozen new directories at once. Restart the dev server before concluding the translations are broken.

Troubleshooting

For the __MSG_key__ mechanics behind the third row, see __MSG_key__ substitution in manifest.json.

Quick reference

Frequently asked questions

Related guides

• •The messages.json format explained — the file format itself, unchanged by Plasmo.
• •Chrome extension _locales structure — valid folder names and the lookup fallback chain.
• •default_locale: rules and common errors — the field Plasmo guesses for you if you omit it.
• •WXT i18n: @wxt-dev/i18n and messages.json — how the other popular extension framework handles the same problem.