Translate Like a Pro | Browser Extension Localization

A browser extension is a small product living inside a larger product whose language, permissions and UI rules it does not control. Localizing it means more than translating a popup. The extension name, description, action title, context menus, options page, notifications, store listing, permission explanations and runtime messages can all appear in different surfaces with different constraints.

Searches for browser extension localization, Chrome extension i18n, Firefox extension localization, messages.json localization, default_locale extension, _locales browser extension and WebExtensions internationalization point to a defined architecture. Chrome’s extension internationalization system uses _locales directories and messages.json resources, while MDN documents default_locale and locale fallback behavior for WebExtensions.

This guide explains how to localize extension manifests, popups, options pages and runtime UI without translating permission identifiers or breaking cross-browser behavior. It covers _locales, default_locale, message keys, manifest __MSG_ placeholders, runtime i18n APIs, locale fallback, CSS localization, placeholders, permissions, host access, keyboard shortcuts, context menus, notifications, store metadata, content scripts, injected pages, cross-browser differences and final extension QA.

This article is part of eduKateSG’s Master Art of Translation architecture. It extends the professional localization layer without replacing the existing owners for file preparation, Unicode, software localization, permission flows or general quality assurance.

Quick answer

Keep extension configuration and permissions structurally stable while moving user-facing strings into the platform’s localization resources. Define default_locale correctly, localize manifest-facing text through message keys, preserve permission and host syntax, test fallback behavior, and run the built extension in each supported browser and locale.

Inventory: find visible strings in manifest, popup, options, menus, notifications and injected UI.
Externalize: move language into messages.json or the platform’s i18n resources.
Default: define default_locale when locale resources exist.
Protect: keep permissions, host patterns, command IDs and internal message keys stable.
Fallback: know what happens when a target string is missing.
Cross-browser: test Chrome/Chromium and Firefox behavior where supported.
Publish: align extension-store metadata with the localized installed experience.

1. Use the extension platform’s i18n resource structure

Chrome and WebExtensions support locale-specific resource directories. Centralized message files make strings discoverable, reusable and testable.

Professional method. Place locale messages under the documented _locales//messages.json structure and access them through the extension i18n API. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Strings remain hard-coded in popup HTML and JavaScript. A tooltip can be referenced through a message key rather than copied into several files.

Verification. Search the built package for visible source-language literals. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

2. Set default_locale correctly

When an extension contains _locales resources, the manifest’s default_locale identifies the fallback language. MDN documents that default_locale is required when the _locales directory is present.

Professional method. Choose the real authored fallback locale and keep the directory naming consistent with platform rules. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. The extension has locale directories but no default locale and fails packaging or fallback. default_locale: en points to _locales/en/messages.json.

Verification. Remove one non-default string in a test locale and observe the documented fallback. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

3. Keep message keys stable

The key identifies the concept used by code and manifest resources. Translating keys would break lookups.

Professional method. Use stable semantic identifiers such as extensionName, contextMenuSave or errorNoSelection. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Each locale invents a translated key name. The value of contextMenuSave changes while the key stays identical.

Verification. Compare key sets across locales automatically. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

4. Localize manifest-facing strings through __MSG_ tokens

Chrome documentation supports message substitutions such as __MSG_extensionName__ in the manifest. The manifest itself contains visible metadata but also machine configuration.

Professional method. Replace only localizable manifest string values with approved message placeholders. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A translator edits JSON structural keys or permission arrays. name can reference a localized message while version and permissions remain fixed.

Verification. Load the extension under several browser locales and inspect name/tooltip. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

5. Protect permissions as capability identifiers

Extension permissions such as storage, tabs or host access are machine configuration. Translating them can invalidate the manifest or change requested capability.

Professional method. Lock permission identifiers and localize only user explanations around them. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A permission string is translated because it looks like an English word. storage remains the literal manifest capability while onboarding can explain why storage is used.

Verification. Compare built manifest permission arrays to source control. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

6. Keep host patterns and URLs exact

Host permissions and match patterns define where the extension runs. Changing domains, wildcards or path syntax alters behavior and security.

Professional method. Protect patterns and use separate localized labels for site names. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A translator converts a punycode or hostname into display text inside a permission pattern. https://*.example.com/* remains machine syntax while UI says ‘Access Example sites’.

Verification. Run permission and content-script tests. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

7. Localize action titles and tooltips

The extension action is often the first visible browser UI. Short strings need clear target-language action semantics.

Professional method. Use i18n message keys for action titles and test truncation or tooltip behavior. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A literal translation is too vague to explain the toolbar action. ‘Save page’ may need a more explicit target verb depending on context.

Verification. Hover and keyboard-focus the action in each locale. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

8. Localize context-menu items with surrounding browser context in mind

Context menus appear among browser-native localized entries. Register and grammar should fit the environment.

Professional method. Translate concise action phrases and test with selected text, links, images and pages as applicable. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. The extension item uses a full sentence while surrounding browser entries are compact commands. A save-image extension can use a natural imperative aligned with target OS/browser style.

Verification. Open context menus in real target-language browser UI. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

9. Translate popup and options UI as normal product surfaces

Extension pages can contain forms, settings, validation and help. They deserve the same full-context localization as a small web app.

Professional method. Externalize strings, localize dynamic messages and test layout expansion. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Only the extension name is localized while settings remain source language. An options page can use the same translation quality practices as other software UI.

Verification. Complete the main settings workflow in the target locale. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

10. Use placeholders for dynamic message content

messages.json supports placeholders for values inserted at runtime. Concatenating dynamic strings fixes source-language order.

Professional method. Define placeholders with descriptions and complete target message patterns. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Code builds ‘Saved ‘ + count + ‘ items’. A localized message can move the count according to grammar.

Verification. Render each message with representative values. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

11. Document placeholder meaning for translators

Placeholder syntax does not explain semantics. A translator needs to know whether $1 is a domain, count, user name or error text.

Professional method. Use message descriptions and translator documentation. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. The target places a domain into a grammatical position intended for a person. description: ‘Name of the current website’ gives useful context.

Verification. Review the extracted locale resource without source code. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

12. Understand locale selection and fallback

WebExtensions can try exact locale, broader language variants and default locale depending on platform behavior. Missing regional resources do not always mean missing output.

Professional method. Test locale chains such as region/script variants and document which locales you actually ship. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A team duplicates all strings for en-US and en-GB unnecessarily or assumes fallback that the target browser does not perform identically. MDN describes progressively broader locale selection before default_locale.

Verification. Test missing-string behavior in each supported browser. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

13. Localize CSS-dependent assets carefully

MDN documents use of localized strings in CSS in WebExtensions. Locale-dependent assets can improve fit but can also fragment visual resources.

Professional method. Use this capability only when asset variation is genuinely required and keep styling semantics consistent. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. Every locale gets a separate decorative image with no governance. A text-bearing background asset may need a locale-specific replacement.

Verification. Inspect the built CSS and visual result under each locale. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

14. Keep keyboard command identifiers separate from shortcuts

Command IDs are internal while actual shortcuts can have platform constraints and user overrides. Translating an identifier or hard-coding locale-specific key assumptions can break commands.

Professional method. Protect command names and localize the user-facing description; follow existing shortcut policy. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A command key in manifest is translated. _execute_action stays fixed while description becomes target-language text.

Verification. Trigger the shortcut and inspect extension command settings. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

15. Localize notifications without changing origin or severity

Extensions may produce browser notifications for errors or results. The message can carry security or privacy meaning.

Professional method. Use complete localized templates and preserve the exact event state. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A warning becomes an informational tone in one locale. A blocked tracker notification should not claim a threat was removed if the extension only detected it.

Verification. Trigger each notification state. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

16. Keep content-script injected UI isolated from host-page language assumptions

Extensions can inject controls into websites whose language differs from the browser locale. The user’s browser language, page language and extension preference may conflict.

Professional method. Define which locale drives injected extension UI and avoid inheriting host-page strings accidentally. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. An English browser extension changes language based on one French webpage. The extension can consistently follow browser locale unless the product offers its own language setting.

Verification. Open pages in several content languages under one browser locale. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

17. Align store listing and installed extension

Extension-store metadata can be localized separately from the extension package. A localized listing that installs a source-language interface breaks continuity.

Professional method. Coordinate store descriptions, screenshots and extension resources under the same locale readiness. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. The store page promises Spanish support while settings remain English. Screenshots should show the localized popup users actually receive.

Verification. Install from the target-language store listing. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

18. Regression-test cross-browser packaging and fallback

Chrome and Firefox share much of WebExtensions but differ in details. A localization feature or manifest rule can behave differently across supported browsers.

Professional method. Use browser-specific build/test matrices in the localization regression suite. Write the rule down so that another translator, reviewer, engineer or product owner can apply it consistently in the next locale or release.

Failure mode. A locale passes Chrome but default-locale handling differs in Firefox packaging. Automated tests can verify key presence and human smoke tests can inspect browser chrome integration.

Verification. Load signed or development builds in each supported browser and locale. If the result depends on a hidden assumption, return to the source, platform behavior, structured data or authoritative specification before approving the localization.

A repeatable operating sequence

A safe browser-extension workflow keeps manifest syntax and permissions invariant while externalizing every user-facing language surface into controlled locale resources.

Inventory manifest-visible and runtime-visible strings.
Move translatable values into messages.json resources.
Define and validate default_locale.
Protect permissions, host patterns, command IDs and internal keys.
Add placeholder descriptions and complete messages.
Localize toolbar, context menu, popup, options and notifications.
Test locale fallback and missing keys.
Test injected UI on pages of different languages.
Align extension-store metadata and screenshots.
Package and run the extension in supported browsers.
Regression-test key parity, manifest integrity and user journeys.
Recheck after browser manifest or i18n API changes.

Treat the sequence as a loop. If final testing reveals a defect, trace it to the earliest useful source—data identity, file metadata, OCR confidence, extension manifest, challenge configuration, context, language resource or platform state—and repair that source rather than patching only the visible symptom.

Worked scenarios

1. Permission translated in manifest

A translator changes ‘storage’ because it appears to be English. The key risk is manifest becoming invalid or semantically different.

Protect capability identifiers and localize only the human explanation. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

2. Missing regional locale

The user runs zh-Hans-CN but the extension ships zh and en only. The key risk is incorrect assumptions about fallback.

Test documented locale selection behavior and add a more specific resource only when language quality requires it. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

3. Injected button follows page language

A user with English browser locale opens a Spanish website. The key risk is extension UI changing unpredictably with host content.

Use the extension’s defined locale source and keep host-page language separate unless the product intentionally adapts to it. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

4. Store page localized, popup not

The extension marketplace listing is German but _locales/de is incomplete. The key risk is acquisition promise breaking at install.

Gate the localized listing on installed-experience readiness. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

5. Placeholder lacks meaning

The target message contains $1 with no description. The key risk is wrong grammatical treatment.

Add translator context describing the runtime value and render examples before approval. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

6. Firefox and Chrome differ after update

One browser changes manifest or localization behavior. The key risk is assuming cross-browser parity forever.

Keep a release matrix and rerun packaging/fallback smoke tests after major browser updates. Then verify the decision in the actual product path. Localization is not complete when the text looks plausible in a spreadsheet; it is complete when the user and the system still agree about what the object, action or state actually is.

Browser-extension localization: twenty professional practice cases

For each case, identify the invariant, the localizable layer, the evidence needed to decide, and the final release test.

1. The manifest name is user-visible

Use a message placeholder; do not translate JSON keys. State one reason for the decision and one condition that would make you revisit it. That turns a preference into a transferable professional rule.