default_locale: rules and common errors

The fundamental rule

Chrome enforces a strict coupling between default_locale and the _locales directory. The rule has two sides:

Error: “default_locale is required”

This is the most common mistake. You add a _locales/ folder with translated files but forget to add default_locale to the manifest.

Chrome DevTools error:

Could not load extension from ‘/path/to/my-extension’.
Manifest file is invalid.
default_locale is required if _locales/ is present.

Fix — add default_locale to manifest.json:

{
  "manifest_version": 3,
  "name": "__MSG_appName__",
  "default_locale": "en"   ← add this
}

The value must be a locale code that has a corresponding folder inside _locales/. If default_locale is "en", there must be a _locales/en/messages.json file.

Error: “_locales/ directory missing”

The opposite mistake: you declare default_locale but either never created _locales/ or accidentally deleted it.

Chrome DevTools error:

Could not load extension from ‘/path/to/my-extension’.
Manifest file is invalid.
_locales directory is missing or inaccessible.

Fix:

# Create the required folder structure
mkdir -p _locales/en

# Then add _locales/en/messages.json with at least one key
echo '{ "appName": { "message": "My Extension" } }' > _locales/en/messages.json

Error: default_locale folder is missing from _locales/

A subtler variant: you have default_locale declared and a _locales/ folder, but the folder for the declared default locale is absent. For example, default_locale is "en" but only _locales/de/ exists.

Could not load extension from ‘/path/to/my-extension’.
Catalog file is missing for locale en.

Fix:

_locales/
├── en/                     ← must match default_locale exactly
│   └── messages.json
└── de/
    └── messages.json

Error: invalid locale code in default_locale

Chrome only accepts locale codes from its approved list. An unrecognised value in default_locale will fail validation.

What default_locale controls at runtime

Beyond validation, default_locale defines the fallback chain Chrome uses when a locale is unavailable:

User locale: zh_TW (Traditional Chinese)

Chrome lookup order:
  1. _locales/zh_TW/messages.json   ← specific variant
  2. _locales/zh/messages.json      ← parent language (if zh_TW not found)
  3. _locales/en/messages.json      ← default_locale (if zh also not found)

Result: always returns a string, never throws.

This means you can ship a small set of locales and rely on default_locale for the rest. Users whose language is not translated will see your source strings rather than a broken experience.

How the Chrome Web Store validates default_locale

The Web Store runs the same manifest validation as Chrome itself when you upload a ZIP. Additionally, it checks that:

• •default_locale matches a folder in _locales/.
• •Every _locales/*/messages.json file is valid JSON.
• •Every key used in __MSG_key__ manifest substitutions exists in the default_locale messages.json.

Upload failures from these checks result in a rejection email with a message like “Your item was found to have errors” and a reference to the manifest field at fault.

Removing i18n from an existing extension

If you decide to remove i18n support from an extension that previously had it, you must remove both sides of the pair together:

# 1. Remove default_locale from manifest.json
{
  "manifest_version": 3,
  "name": "My Extension",   ← plain string, not __MSG_appName__
  "description": "...",
  "version": "1.0.0"
  // no default_locale
}

# 2. Delete the _locales/ directory entirely
rm -rf _locales/

Quick reference