Fix: Localization used, but default_locale wasn't specified in the manifest
7 min readModerok team
Why Chrome refuses to load an MV3 extension with this error, the default_locale manifest fix, and why chrome.i18n.getMessage still returns an empty string.
When Chrome refuses to load your extension with Localization used, but default_locale wasn't specified in the manifest., add default_locale to manifest.json and make sure the matching message catalog exists on disk:
{
"manifest_version": 3,
"name": "__MSG_extName__",
"version": "1.0.0",
"default_locale": "en",
"background": { "service_worker": "background.js" }
}
_locales/
en/messages.json
de/messages.json
Chrome's i18n reference states the rule in one sentence: "If an extension has a /_locales directory, the manifest must define "default_locale"." The default_locale manifest page adds the other half: the field is "required for localized extensions (those with a _locales directory)" but "must be absent in extensions that have no _locales directory."
That is the common case. The rest of this post is the uncommon one: Chrome prints the same error when default_locale is in your manifest.
Why Chrome says default_locale wasn't specified in the manifest when it is
The string comes from Chromium's extension loader, not from a manifest schema check, and the docs do not list it. In extensions/common/file_util.cc, LoadMessageBundle runs only if a _locales folder exists, and then takes this branch:
base::FilePath default_locale_path = locale_path.AppendASCII(default_locale);
if (default_locale.empty() || !chrome_locales.contains(default_locale) ||
!base::PathExists(default_locale_path)) {
*error = l10n_util::GetStringUTF8(
IDS_EXTENSION_LOCALES_NO_DEFAULT_LOCALE_SPECIFIED);
return nullptr;
}
IDS_EXTENSION_LOCALES_NO_DEFAULT_LOCALE_SPECIFIED resolves to exactly the error you are reading, per extensions/strings/extensions_strings.grd. So there are three distinct faults behind one message:
default_localeis missing. The documented case.- The value is not one of the locale names Chrome knows. The comparison is against Chrome's own locale list, which uses the underscore form.
"default_locale": "pt-BR"fails this test where"pt_BR"passes. The i18n docs use the same convention, noting a locale "has an underscore:_", and they warn: "If you use an unsupported locale, Google Chrome ignores it." _locales/<default_locale>/does not exist. Spelling, casing, or a build step that copied_localesto the wrong place inside the package. The path is built by appending your literal string to_locales, soen_USin the manifest needs a folder nameden_US, and that name also has to survive test 2 (which is whyen-UScannot be rescued by renaming the folder to match).
The failure happens while the manifest is being localized, so the extension does not load at all: no service worker to inspect, no console to read, the same shape of problem as a worker that dies during its first evaluation. Reload the extension from chrome://extensions after fixing it; a manifest edit is not picked up by refreshing a page.
The mirror image, and the other load errors
Chromium's DefaultLocaleHandler::Validate in default_locale_handler.cc carries the comment "default_locale and _locales have to be both present or both missing" and enforces it in both directions:
_localespresent, nodefault_locale: the error above.default_localepresent, no_localesdirectory:Default locale was specified, but _locales subtree is missing.- A locale folder with no
messages.jsonin it:Messages file is missing for locale.followed by the path. Only folders whose names Chrome recognises as locales are checked, and the validator skips names containing a dot (the code comment names.svn). An emptyde/left behind by a translation tool blocks the load; a straytranslations-backup/beside it is ignored. - A
_localestree whose default locale folder is skipped or unreadable:Default locale is defined but default data couldn't be loaded.
One more comes from the manifest parse step: if default_locale is not a string or not a parseable language tag, you get Invalid value for default locale - locale name must be a string.
When the extension loads but chrome.i18n.getMessage returns an empty string
A correct default_locale fixes loading, not lookups. chrome.i18n.getMessage has no error channel. The i18n reference is explicit: "If the message is missing, this method returns an empty string ('')." So a typo in a message name produces a blank label and nothing else.
Four rules decide whether a lookup resolves:
- The key must be in a catalog Chrome actually loaded. Chrome searches the user's preferred locale, then that locale without its region, then the default locale, and
extension_l10n_util.ccwalks the browser's own locale and its parent locales in between, so a browser set toen_GBtriesen_GBand thenen. The i18n reference gives you the safety net to aim for: "As long as the default locale'smessages.jsonfile has a value for every string, your extension or app will run no matter how sparse a translation is." - Entries need both required fields. The message formats page says: "Only the "name" and "message" fields are required." It also says "The name is a case-insensitive key that lets you retrieve the localized message text", so casing drift between
messages.jsonand your call is not the bug. - Nine substitutions, maximum. The i18n reference says: "In each call to
getMessage(), you can supply up to 9 strings to be included in the message." Go over, or pass a non-string message name, and the return value isundefinedrather than"", which is worth distinguishing when you log the failure. __MSG_name__works in a fixed set of manifest keys. Chromium'sLocalizeManifestsubstitutesname,short_name,description, theaction/browser_action/page_actiondefault titles, the omnibox keyword and command descriptions, among a short list. In any other key the literal text stays.@@extension_idis a separate restriction: it is for CSS and JavaScript, and MDN says plainly, "You can't use this message in a manifest file."
What still breaks after the manifest is right
A broken catalog in a non-default locale is invisible to you. At runtime Chrome loads only the catalogs in the current fallback chain, so malformed JSON in fr/messages.json breaks the extension for French users alone. A comment in extension_l10n_util.cc notes that the pass which loads every locale and reports Invalid locale file '<path>': <detail> for each "only gets used when reloading unpacked or packing extensions." Reloading the unpacked build is therefore a real check, and linting every messages.json is a better one.
Test other locales with a launch flag, not the settings UI. The i18n reference gives a per-locale profile: path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir on Windows, or quitting Chrome and relaunching as LANGUAGE=es ./chrome on Linux. It prefers that to the settings route, which ends in a restart: "Once you've set it up, the shortcut approach is quicker and lets you use several languages at once."
Firefox differences
Firefox implements the same API with two differences that change what you see, and one that only looks like a difference.
Missing messages are noisier. MDN's getMessage page splits the behaviour in two for a message that "can't be found in messages.json": "Firefox returns "" and logs an error." and "Chrome returns "" and does not log an error." Running the same build in Firefox is the cheapest way to find missing keys.
And @@extension_id means something else. MDN describes it as the extension's internally generated UUID and warns it is "not the add-on ID returned by runtime.id", so a URL built from it is per-install, not per-extension. Firefox also runs your MV3 background as an event page rather than a service worker, which changes where your background code lives but not how lookups resolve.
The apparent difference is the fallback chain. MDN's guide lists the browser locale, "the file for the regionless version, e.g., zh-Hans", then "the file for the scriptless version, e.g., zh", then the default locale. Chrome's docs never mention the scriptless step, but Chromium walks the same parent chain, so MDN's list describes both browsers.
Make the silent empties visible
Localization bugs survive release because an empty string looks like a design decision. A guard costs a few lines, and reporting the miss costs one more:
function t(name, ...subs) {
const value = chrome.i18n.getMessage(name, subs.length ? subs : undefined);
if (!value) {
Moderok.captureError(new Error(`missing i18n message: ${name}`), { message_name: name });
return name;
}
return value;
}
Moderok's SDK records that as an __error event, and each event already carries the browser locale from navigator.language in its context, so a miss arrives with the locale it happened in. One caveat if you wrap a whole view in that helper: once init() has run, error capture is rate limited to 20 events per minute per JavaScript context, a budget shared with the uncaught exceptions and rejections the SDK records on its own, and a repeat of the same missing key inside that window is deduplicated. A view with 30 distinct misses reports 20 of them, and says so in the console only when debug is on. The error tracking API is documented in the Moderok error docs, and the wider case for catching failures that never throw is in Chrome extension error tracking in production.