How People Translate Quickly | Chrome Extension _locales: Translate Popup Text Without Breaking Message Keys

To translate a Chrome extension quickly, create language-specific messages.json files under _locales, keep the message identifiers stable, and change the human-readable message values rather than the lookup contract. The extension manifest must declare a default_locale when localization resources are supplied. Translate the popup, action tooltip, options page and user-facing error explanations as one experience, then reload the unpacked extension and test the actual display in each target browser locale.

Chrome extension localization is not the same job as translating a webpage or a React application's ordinary JSON dictionary. A manifest can refer to messages with __MSG_identifier__, while JavaScript retrieves values through chrome.i18n.getMessage(). Placeholders have their own syntax and substitution rules. If a translator renames a key, translates a placeholder token, or assumes that changing a resource file automatically replaces literal text in HTML, the package may load while the user still sees English strings or empty labels.

This guide gives a practical Chrome Manifest V3 localization workflow using a fictional school reading-helper extension. It separates message text from application behavior, walks through an illustrative but structurally meaningful resource example, explains fallback and bidirectional display limits, and supplies diagnostic tests, repair procedures, a changed-context exercise and an independent review checklist. These examples do not claim to be production-ready extension source; Chrome's current documentation is the authority for API details and supported locales.

Begin with one visible task, not every file in the repository

The reader's immediate problem is straightforward: a school wants its extension to show an understandable popup in English and Spanish, but the extension must still open the correct reading list when the learner selects a button. The developer already has a functioning build. The translator must not turn a language change into a feature change. Start by loading the extension in its default locale, taking screenshots of its popup, tooltip, options screen and error messages, and listing each phrase that the learner can actually encounter.

This visible inventory is more useful than searching for every English word in the source tree. A repository may contain comments, test fixtures, URLs, CSS selectors, command names, permission declarations and log statements that are not intended for translation. Some look like ordinary English. Translating them could break the extension's runtime behavior, invalidate a selector or alter security-sensitive permissions. The initial list should connect a user-facing expression to a screen, the user action that reveals it, the owning source file and a proposed stable message key.

For the reading-helper example, imagine a popup title, a button to open the current reading list, a button to save a page, a status message describing a saved item count and a permission error. These are five very different kinds of content. The popup title is a noun phrase, the two buttons are actions, the count is a variable sentence and the permission error must explain a real restriction. Treating all five as interchangeable labels causes awkward, ambiguous translations. A small screen inventory makes the difference visible before anyone edits JSON.

Understand the Chrome resource contract before translating

Chrome's extension internationalization model resolves messages by identifier from locale directories. A localized extension places a messages.json file in each supported directory beneath _locales/; its manifest declares a default language through default_locale. The default directory must be present and complete enough to provide the strings the extension expects. A target locale can be partial because Chrome looks for a message through its documented fallback sequence, but a fallback that prevents a crash is not necessarily an acceptable bilingual experience.

Within each messages.json file, a top-level message identifier maps to an object whose message field is shown to users. An optional description field helps developers and translators understand the purpose of the message; it is not the text presented in the popup. Placeholders allow a message to accept arguments supplied at runtime. A translator can reorder prose around a placeholder to match target-language grammar, but must keep the placeholder's identity and syntax intact so the extension can substitute the correct information.

The resource key is an interface between code and copy. Code can ask for savedCount; it cannot guess that a translator renamed the key to numeroGuardados. A translated name might look more natural to a reader looking directly at the JSON file, yet no learner ever sees that key. The reader sees only the resolved message. Good localization therefore preserves stable internal identifiers and spends its creative effort on accurate, concise, action-oriented phrases in the message value.

Separate manifest lookups, JavaScript lookups and static HTML

An extension has several surfaces that require different retrieval paths. Chrome's manifest can use a localization placeholder such as __MSG_extensionName__ for localizable manifest fields. JavaScript can call chrome.i18n.getMessage('openReadingList') and assign the returned text to a button safely. Static HTML does not magically convert every arbitrary attribute or visible English sentence into a localized resource simply because _locales/es/messages.json exists. The page script needs to place resolved strings into the appropriate DOM nodes.

A common partial failure is a localized extension name in the toolbar accompanied by an English popup. The developer translated extensionName and used the manifest placeholder, but left hard-coded HTML inside the popup. Another is a translated popup heading with an English browser-action tooltip because action.default_title was not wired to its message. These two symptoms arise from different source locations; both require inspecting the actual lookup. A translator who only validates JSON syntax can miss them entirely.

An inventory table should therefore record the consuming mechanism for every string: manifest substitution, JavaScript getMessage, dynamically generated notification, accessible label or other product-specific rendering. The same apparent phrase can have distinct contexts. A button titled “Save” might save the article, while another “Save” might preserve extension settings. Give them different keys and descriptions when their grammatical context or consequence differs. That slight upfront discipline prevents a later translation from being grammatically valid but operationally misleading.

A small resource example with real placeholder discipline

The following illustration uses a default-language dictionary and one target-language dictionary. Its intentionally short keys remain identical across locales. The savedCount template uses the documented Chrome message placeholder mechanism: the displayed message contains $count$ , while the placeholders object defines the positional substitution $1. The JavaScript caller must provide the value. The accompanying description gives translators meaning and context; it does not appear on screen.

{
  "extensionName": { "message": "Reading Helper", "description": "Toolbar extension name" },
  "openList": { "message": "Open reading list", "description": "Popup primary button" },
  "savedCount": {
    "message": "Saved pages: $count$",
    "description": "Status line; count is a nonnegative integer",
    "placeholders": { "count": { "content": "$1", "example": "3" } }
  }
}

{
  "extensionName": { "message": "Ayudante de lectura", "description": "Toolbar extension name" },
  "openList": { "message": "Abrir lista de lectura", "description": "Popup primary button" },
  "savedCount": {
    "message": "Páginas guardadas: $count$",
    "description": "Status line; count is a nonnegative integer",
    "placeholders": { "count": { "content": "$1", "example": "3" } }
  }
}

The Spanish wording is an illustrative editorial choice, not proof of suitability for every Spanish-speaking community. A reviewer should still confirm terminology with the product owner and target users. The more important structural check is that both files expose the same message identifiers and that the placeholder is a named slot, not a number typed directly into the translated text. If the source changes from “Saved pages” to “Saved articles,” the translation must be reviewed as a meaning update even if the placeholder signature is unchanged.

A corresponding runtime call might use chrome.i18n.getMessage('savedCount', String(count)), then insert the result with a text-only DOM API. In production, the developer should verify that the target element exists and the result is nonempty. Do not use a translator-controlled string as executable HTML merely to display a localized label. When strings contain punctuation, apostrophes or user names, treating them as text reduces avoidable rendering and injection risks.

Why placeholder names and substitution positions are different things

A placeholder's display name helps the translator understand the sentence; its underlying content determines how Chrome supplies a value. The count name in $count$ should remain stable across the two dictionaries. The $1 reference in the placeholder definition means the first substitution value supplied by the caller. If a future message needs an item title and a total count, the developer may supply two values and define separate named placeholders whose contents refer to the appropriate positions.

Suppose a new status reads “Saved $title$ as item $count$.” The translated language may place the ordinal or noun before the item title. Reordering $title$ and $count$ inside the message is possible when the definitions are preserved, but changing content from $1 to $2 without matching the caller will swap values or produce incorrect output. Counted values are especially visible to learners because a wrong number makes the interface appear unreliable even when the underlying reading list is correct.

A reliable placeholder audit compares the set of named placeholders in each target message with the source, checks any positional references against the caller's arguments, and renders test values that are unmistakably different. Using 3 for both a page count and an item identifier can hide a swap. Try a title such as “Planet Earth” and a count of 17 so the wrong mapping is obvious. Also test special characters and long translated words. The audit should flag missing and unexpected placeholders, not reject legitimate changes to word order.

The default locale is a safety net, not a complete localization plan

Chrome's documentation describes the fallback sequence from a requested locale to a language-only directory and then to the declared default. This is valuable because not every region needs a separate translation file. A browser configured for a regional variant may resolve a common language resource when the regional directory or key is absent. That behavior helps an extension remain functional. It does not prove that the correct tone, terminology or legal wording appears for a particular audience.

Consider a Spanish-language popup with four translated labels and one English permission warning. An automated check that opens the popup and observes no exceptions may report success. A learner facing a permissions problem still has the hardest sentence in an unfamiliar language. For a school product, warning and recovery text should often be higher priority than a decorative heading. The inventory should mark critical messages whose fallback to the default language is unacceptable for the intended release.

For each supported target locale, build a coverage report from the default message keys. Mark present, absent, intentionally inherited and obsolete entries separately. A missing entry might be a deliberate regional reuse or an accidental omission. A translator should never infer that a successful fallback means the phrase was translated. Publish a known exception list, review it with the product owner, and test on a browser configured for the locale rather than relying only on an English developer machine.

Locale directory names are part of the product contract

Chrome documentation uses locale directories such as en, es, and region-specific forms such as en_GB. Those path names are not arbitrary file labels; the extension's lookup system determines which directory it searches. Renaming _locales/es to a friendly folder such as _locales/Spanish will not produce the intended localization. The manifest's default_locale must match the actual default-language directory, and each directory must contain a correctly formed messages.json file.

Before creating a new region-specific dictionary, ask whether the vocabulary truly differs. An unnecessarily separate es_MX copy can age out of sync with the parent Spanish translation, while a missing regional distinction can be harmful when a technical or culturally sensitive term changes meaning. Separate the decision to support a locale from the decision to fork every string. Keep one ledger recording the browser locale, directory used, source revision, translator and release status.

Test the fallback path explicitly. Configure a regional locale for which a complete regional file exists, one with only a base-language resource, and one with no supported language resource. Record the strings displayed in each. This turns fallback from invisible magic into a measurable behavior. If a learner's browser reports a language the product does not support, the extension should still present its declared default consistently rather than mixing stale strings from an accidental directory.

Translate actions according to consequences, not word length

A cramped extension popup encourages very short labels, yet brevity is not always clarity. “Open list” tells learners that clicking changes the view; “View saved pages” may convey the destination better for a product whose main task is reviewing articles. “Save this page” describes a reversible bookmarking action. “Submit page” could imply uploading data to a school server, a materially different consequence. The translator must ask the developer exactly what happens after clicking before choosing an equivalent.

A good translation brief includes a screenshot, the associated keyboard shortcut if one exists, the visible success state, and whether the action performs a local or network operation. The product may save page URLs locally without uploading page content. A translation that suggests uploading the student's browsing history creates a false privacy expectation and undermines trust. A short phrase can still include the decisive noun or verb if its surrounding screen context is known.

Prefer consistency, not identical wording at all costs. A tooltip, menu item and error message can refer to the same destination with different grammar because their functions differ. Consistency means the same concept, such as “reading list,” retains its chosen name. It does not mean every sentence should mechanically reuse an English word order. Review labels while they are rendered in the actual popup. The best translation often emerges only after seeing the whole screen and the state it controls.

Make errors actionable in the student's language

A message such as “Permission denied” may be technically accurate but leave a learner without a repair path. The source owner should explain which permission is missing and what the person can do next. The translation can then preserve that operational meaning: for example, “This page cannot be saved until the extension can access this site. Open extension settings to review access.” Exact settings wording depends on the current browser interface and product design; the localized extension should not promise a button that is absent.

Error translations are easily distorted by overconfidence. “Cannot reach the school server” is not interchangeable with “Your internet is disconnected”; the first could result from a server outage, a blocked request, authentication or several network conditions. A translator who guesses a specific cause creates a false diagnosis. Ask the developer which errors are known and which are ambiguous. Keep uncertain messages appropriately uncertain while offering a safe retry or support route.

Test the error at the point where it happens. A screenshot of a translated sentence in a spreadsheet does not establish that the extension will display it after a denied permission or offline request. Deliberately reproduce the failure using a test account and safe fixture. Observe the message, confirm the implied action exists, and verify that a successful retry changes the state correctly. In school software, the recovery wording can determine whether a learner completes the task without adult assistance.

Design and accessibility review must use real strings

Translated text can be longer than its source. The Chrome popup may have a narrow fixed width, an icon beside each command and a scrolling area. A long target-language button label could wrap over a control, clip at the edge or push a status message below the fold. An editor's word count cannot predict the problem because glyph width, font and script shaping matter. Test rendered labels at normal zoom, increased browser zoom and a representative high-density display.

Do not solve every overflow problem by deleting meaningful qualifiers. If “Open the teacher-approved reading list” becomes merely “Open,” the learner loses an important distinction. First adjust layout, allow wrapping, use a shorter but specific phrase, or divide a crowded control into a title and supporting text. Make the tradeoff in the actual interface with an accessible name for the control. A visually short icon-only button may still require a clear accessible label retrieved from the same localized resource.

Keyboard and assistive-technology review should include the translated focus sequence, button purpose and visible feedback after action. Avoid adding decorative punctuation to a screen-reader label just to imitate English. For languages using different reading directions, check alignment and icon placement with actual content. Mirroring the entire interface without understanding direction-sensitive controls can place arrows or progress indicators on the wrong side. Chrome provides locale and bidirectional helpers, but using those helpers correctly still requires product-specific testing.

Treat language direction as more than a left-right CSS swap

A right-to-left interface might contain left-to-right URLs, page titles, file names and version numbers. The popup can therefore contain mixed-direction runs. A naive global direction flip can make a web address look broken, while leaving everything left-to-right can make Arabic or Hebrew instructions awkward to follow. The translator needs a test fixture combining a translated phrase, an English domain, a numeric count and punctuation to reveal how the browser resolves direction.

Chrome's predefined internationalization messages include direction-related values. They can inform styling, but the developer must still verify semantic reading order, accessible labels and context-specific alignment. Some icons have directional meaning, such as “previous page,” while others, such as a magnifying glass, do not need mirroring. Controls containing numbers may require isolation so the digits remain intelligible within the surrounding sentence. Reusing a desktop CSS direction rule blindly in a narrow extension popup can yield a confusing result.

When a target language lacks in-house reading expertise, ask a qualified reviewer to evaluate a screenshot and an interactive build. The reviewer should not merely approve spelling; they should follow a task: save a page, confirm the count, reopen the list and recover from an error. That task reveals whether direction, wording and input order work together. A string can pass linguistic inspection in isolation and still fail at the exact moment a learner needs it.

Use a translation ledger with a clear approval trail

A simple ledger can prevent most accidental changes. Give each message key a row with source text, source revision, context screenshot, target text, placeholder signature, length observation, owner, reviewer and state. The goal is not an elaborate bureaucracy. It is to distinguish a translation that has been reviewed against the current source from a plausible phrase copied from last year's extension. If a developer changes a command's behavior, the source revision should invalidate the old approval.

Separate the role of translator from the role of code owner. The translator owns linguistic equivalence, terminology and audience comprehension. The developer owns the message extraction, API consumption, placeholder arguments and runtime behavior. A teacher or learning-product owner confirms that the label describes a real learning action. A release reviewer checks the built artifact. One person may fill several roles on a small project, but writing down the roles still reduces blind spots.

When several locales are being prepared, avoid merging their files solely on timestamp. A late modification to messages.json could come from a valid source change, a machine-generated update or an unrelated branch. Inspect the keys and changes. A target file that includes unknown keys may be harmless but should be explained; a target file missing a critical key should block the relevant locale release. Archive the accepted dictionary alongside the extension version so reported language defects can be reproduced later.

Validate JSON structure before testing language

A malformed JSON file can prevent the intended resource from loading. Parse every locale dictionary with a strict JSON parser; do not depend on visual inspection of brackets. Check that each top-level identifier maps to an object and that each expected message is a string. Compare keys with the default dictionary, detect duplicates before parsing if the tooling supports it, and check for unexpected placeholders. A parser alone may silently accept the last of duplicate object keys, so a duplicate-key detection pass gives stronger evidence.

Be careful about text that looks like syntax. A translated apostrophe inside a JSON double-quoted string is normally ordinary content, while an unescaped double quote can end the string. A backslash may introduce an escape sequence. Copying strings through a spreadsheet can introduce unusual quotation marks, line endings or a hidden byte-order mark. Export from a controlled UTF-8 pipeline and inspect the actual bytes of the final file when a loader reports unexplained failures.

A useful minimal test loads each dictionary independently, enumerates the keys and compares placeholder names against the default file. Do not automatically reject every extra key: it may be a planned, locale-specific experiment or a transitional message from a branch. Instead classify it as a discrepancy requiring owner review. The highest priority failures are malformed JSON, missing default messages, invalid placeholder definitions and runtime lookups that return an empty string where a visible control needs a label.

Test the packaged extension, not only the repository source

Development files can be correct while the distributable archive omits a locale directory or includes an outdated build. After a local translation review, create a test package from the exact release candidate and install it as an unpacked extension in a clean browser profile. Check that the extension manifest, scripts, popup and target _locales folders have been bundled. A successful repository diff is not evidence that a packaging task copied the resources into the shipped folder.

Test a normal usage sequence from start to finish. Open the popup, save a permitted page, confirm the count, open the saved list, trigger one recoverable error and close and reopen the popup. Record the actual text shown, not merely the expected string from the dictionary. If a locale falls back unexpectedly, inspect the requested browser locale, resource directory and key at the point of lookup. A console log can help the developer, but should never be the sole acceptance criterion.

Include accessibility checks and a narrow regression check in the default language. A translation change should not alter storage keys, saved item identifiers or click handlers. If the Spanish popup looks excellent but the English popup now shows blank labels, the release is not ready. A product serving multiple locales is one product with multiple presentations, so the final QA should cover core behavior across the supported set without asking each translator to reimplement the underlying application tests.

Start by confirming that the browser is using the intended locale, then inspect where the toolbar name gets its content. If the manifest refers to __MSG_extensionName__, Chrome may resolve that placeholder correctly. Next inspect the popup source. Literal HTML such as a hard-coded English <h1> will not be replaced through wishful thinking. The repair is for the developer to retrieve the intended message and populate the correct element, or to use an approved localization pattern within the extension's UI framework.

Do not “fix” the discrepancy by putting translated English words into the default dictionary under a new Spanish-sounding key. That workaround changes the fallback experience for other learners, and the manifest may still use another key. Instead trace the chain from screen element to lookup to dictionary entry. Reproduce the failure after rebuilding. If the source owner adopts a generalized localization helper, verify that it preserves text-only rendering and does not insert untrusted content as HTML.

The evidence of completion is a screenshot of both toolbar and popup in the target locale, plus a successful button action. The screenshot verifies copy visibility; the action verifies that the control still does what it promises. Mark the issue resolved only when both pass. That habit prevents a superficial translation fix from masking a broken event handler.

Diagnostic case: the count displays a literal token

A status line showing $count$ or an empty gap signals a substitution problem, not necessarily a bad translation. Compare the target dictionary's message and placeholders entries with the default. Check whether the target preserved the named token, whether its definition still points to the intended positional argument, and whether the JavaScript caller supplies the argument at all. The source owner should inspect the actual runtime call rather than asking the translator to guess how the application passes data.

If the message uses two arguments, deliberately test different kinds of values. A reading-list title and a numeric count should not swap positions; an optional value should not become an undefined string in the interface. Avoid having the translator insert a literal number to make the screenshot look correct. The number changes as students save pages, and a hard-coded value will become wrong immediately. The repaired resource must still work at zero, one and many saved pages, with any necessary grammatical refinement owned by the source design.

After repair, check another language and the default. A developer may have changed only one locale's placeholder definition in a way that accidentally works with the test fixture. Comparing signatures across all locales is cheaper than discovering the same issue after release. Retest the actual popup with the resource value supplied by the extension rather than a translator's mock-up.

Diagnostic case: a regional user sees unexpected fallback English

First establish the user's configured Chrome UI locale and the default_locale in the extension manifest. Then inspect which _locales directories are inside the installed package. If a browser requests es_MX and there is no regional resource, the implementation may use a language-only resource before the default. If the relevant key is also absent in the base language file, the default message can appear. This can be expected behavior rather than a loader defect, but it should be visible in the release plan.

An audit should distinguish two outcomes: the product intentionally relies on an existing base-language translation, or a critical message was omitted during export. The first may pass; the second should be repaired. Do not add a region-specific directory unless someone will maintain it. An empty regional dictionary can create the illusion of coverage without improving the learner's experience. Use a coverage matrix to document which messages are translated, inherited or blocked from release.

The repair may be as small as restoring one missing key in _locales/es/messages.json, followed by a packaged build test. If the phrase concerns a legally significant consent or privacy message, obtain content-owner approval as well. A correct fallback mechanism can still yield an inappropriate phrase when the user's language and the application's intended content diverge.

Diagnostic case: the translated button fits but misstates the action

A developer sees that the label is short enough and the click handler works. The translator sees a grammatical sentence. The learner, however, thinks “Share page” means sharing the whole page with a teacher when the function only saves a bookmark locally. This is a semantic defect. It will not be caught by a JSON parser, placeholder checker or automated screenshot comparison unless the review criteria include action truthfulness.

Repair the source concept first: document the effect, data destination and confirmation state. Then choose a target-language label expressing that same operation. If the action is “Save bookmark,” do not translate it as “Submit assignment.” Update supporting explanatory text if the product uses a two-line control. Ask a learner or teacher to describe what they expect will happen before clicking; compare their expectation with the actual behavior in a safe test profile.

Record the outcome as more than a linguistic revision. If an interface change clarifies the product's privacy behavior, update the default-language source so future locales inherit the better design. Translation review often reveals a weak original phrase. The right response is controlled source improvement and retranslation, not silently inventing a different feature description in one language.

Build a realistic, bounded review session

For a small extension, divide the session into four gates. The first checks source ownership: are all strings in the inventory and are sensitive behaviors described accurately? The second checks structural integrity: are keys, placeholders, manifest references and JSON valid? The third checks language: are terms, instructions, polite forms and grammatical relationships correct for the audience? The fourth checks actual use: do users complete a representative task in the packaged extension without wrong-language or misleading text?

A single reviewer cannot always cover all of these areas equally well. A teacher may be excellent at learner-facing meaning yet unfamiliar with the Chrome resource API. A developer may know the API precisely but miss a culturally awkward imperative. Split review responsibility explicitly. Keep evidence compact: the extension build identifier, locale, screenshot, test task, observed result and defect number. This is enough to reproduce most failures without writing a huge report that nobody maintains.

Make the test data safe and reversible. A fictional reading article, an empty list, a list of several items and a denied-permission case cover the typical interface states. Do not use real student browsing histories in the localization test bundle. When a bug concerns a saved URL, a neutral example domain is sufficient. This protects learners while still exercising the actual resource paths and UI transitions.

Transfer exercise: localize a bilingual library borrowing extension

Imagine a different extension that reminds students to return borrowed library books. Its default messages include returnReminder, overdueCount, openLoans and renewBook, and the action opens an existing school library page. The Spanish resource includes a translated reminder but changes the overdueCount key to countOverdue. The translator also converts $count$ to a literal number because the screenshot shows two overdue books. Finally, the popup says that renewBook returns the book rather than requesting an extension of the borrowing period.

Your task is to identify which defects are technical, which are semantic and which need a product decision. Decide what the translator may repair alone and what the developer must verify. Also explain how a reader would know whether the extension records a reminder locally or performs a transaction with the library system. Do not assume that a button labelled “Renew” has the authority to renew a real loan. The extension might only open a webpage where the student must sign in and request renewal.

The answer is that the renamed key breaks the contract and should be restored to overdueCount. The hard-coded number must be replaced with the intended named placeholder and matched positional substitution. The renewBook message needs a factually accurate label such as “Open renewal page” if it merely navigates; the source owner must confirm the actual operation before translation. The reviewer should test zero, one and several loans, inspect the target and default languages, and verify that clicking the action does not claim to have changed library records when it has only opened a site.

Practical checklist for the release reviewer

Before sign-off, confirm the exact version of the packaged Manifest V3 extension and the source revision of the default-language dictionary. Every expected key should be accounted for, with absent translations classified as intentional or defects. Parse all dictionaries, check the default_locale path, inspect manifest placeholders and run the JavaScript lookup paths with diagnostic values. Review the target language in its full popup, not only in the exported files.

Review the learner's most important actions: save, open, retry, recover and understand permission limits. Check buttons, tooltips, error messages, accessible labels, counts and the direction of mixed-language content where relevant. Compare the translated copy with the actual effect of each control. A screen that looks attractive but falsely promises an upload, deletion or submission cannot pass a meaning-preservation audit.

Finally, keep a reproducible acceptance record: build hash, locale, test environment, screenshots, approved messages and unresolved exceptions. A successful translation is one that remains attached to the right keys, reaches the intended screen, preserves the action, and helps someone finish the task. The faster workflow is not a weaker review; it is a review that knows exactly which contracts must stay stable and which words may change.

Limits and summary

Chrome extensions differ in framework, browser support, packaging and update paths. A simple popup might use direct chrome.i18n.getMessage calls; a complex application may use a UI framework with its own localization layer. Browser support and locale availability must be checked for the actual target rather than inferred from an example. This guide explains the Chrome extension resource boundary and quality-assurance method, not a complete security audit or a substitute for reading the current Chrome developer documentation.

The central lesson is that a translation file is executable product content even though its most visible part looks like prose. Preserve stable keys, placeholder contracts and behavior; translate the human-facing meaning with context; and verify the packaged experience. A learner should be able to change language without changing what the extension does, where their information goes, or whether they can recover from a problem.

Frequently asked questions

1. Must a localized extension declare a default locale?

If the extension provides a _locales directory, Chrome's extension documentation requires a default_locale in its manifest. The setting identifies the default language directory. Validate this against the actual package rather than assuming a source-tree directory was bundled.

2. Can I translate the keys inside `messages.json`?

Not if the extension uses those keys as stable lookup identifiers. Translate the displayed message value. Renaming openList in one language makes the corresponding runtime lookup fail unless the code changes as well, which is a separate development task.

The manifest may use localized placeholders while popup HTML contains literals. Trace each screen element to the resource lookup. Adding a locale directory alone does not automatically translate arbitrary HTML text.

4. Are message descriptions displayed to end users?

No. A description assists translators and maintainers in understanding the purpose of a message. The message string is the localized content used by the API. Keep descriptions clear enough to prevent grammatical mistakes.

5. How do I preserve changing numbers in a translation?

Use the Chrome placeholder mechanism and supply data through the caller. Compare named placeholders and positional arguments, then render different values. Do not hard-code the count that happens to appear in a screenshot.

6. Does successful fallback mean a locale is complete?

No. Fallback may display a default-language message because the target resource is missing. Record missing messages and decide whether the fallback is acceptable for the intended audience, especially for error and privacy text.

7. Can machine translation replace extension QA?

It can generate a candidate for human review, but it does not establish that resource keys, placeholders, screenshots, actions and packaged files still work. The release gate must test both language and behavior.

8. Should I put translated text into `innerHTML`?

Use a text-safe DOM insertion method for ordinary labels. If the interface genuinely needs markup, the developer should handle that requirement through a deliberately designed and reviewed rendering path rather than treating translation text as arbitrary executable HTML.

9. What if the translated label is too long?

Test the real popup, support wrapping and adjust layout where possible. Shorten wording only when the action remains explicit. Also review focus order and accessible labels so a visual compromise does not create an accessibility failure.

10. How do I verify a regional locale such as British English?

Test the browser's configured locale and the packaged resources, then observe the documented fallback to a language-only or default message when a key is missing. Record actual displayed text rather than inferring it from folder names.

Authoritative current sources

Human SEO metadata (offline editorial only)

SEO title: Chrome Extension Localization QA: Translate messages.json Safely

Meta description: Translate Chrome extension popup text and messages.json without breaking IDs, placeholders, default locales or visible UI. Examples and QA checklist.