Localizing your Firefox AMO listing

Two surfaces, one source of strings

Before anything else, be clear about which surface you are translating. They are edited in different places and they fail in different ways:

The distinction matters enough that we wrote a separate guide on it — see store listing vs in-extension i18n for the full comparison. The rest of this page is about the listing.

What Mozilla lets you localize

Extension Workshop is unambiguous about the scope. From Create an appealing listing:

You also have the option to localize almost all the text content of your add-on’s listing, including its name.

And on how far to take it:

You will want to add a localized listing for each language your add-on supports.

In practice the fields you will be translating are:

• •Name — the add-on title shown in search results and at the top of the listing.
• •Summary — the one-paragraph pitch under the name. Hard limit, see below.
• •Description — the long body copy. Effectively unlimited for authoring purposes.
• •Version details / release notes — per-version, per-locale.
• •Screenshot captions — the text attached to each uploaded screenshot.

The 250-character summary is the real constraint

Everything else on an AMO listing gives you room. The summary does not:

The summary description for your add-on is limited to 250 characters.

Mozilla contrasts this explicitly with the description:

While the add-on summary is limited to 250 characters, you are not practically limited when it comes to the add-on’s description and version details.

That asymmetry is what breaks localization workflows. Translated text is usually longer than English. The commonly used industry rule of thumb for short marketing copy is that German and Russian run roughly 25–35% longer than the English source; it is a planning heuristic, not a guarantee, and individual strings vary a lot. Applied to the summary field it works out roughly like this:

English summary:            248 chars   ← fits, barely
  ↓ translate
German summary:      ~310–335 chars   ← over the 250 limit
Russian summary:     ~310–335 chars   ← over the 250 limit

English summary:            180 chars   ← headroom by design
  ↓ translate
German summary:      ~225–245 chars   ← still fits

If you are generating translations programmatically, enforce the ceiling on the output rather than trusting it. A 251-character summary is not a subtle degradation; it is a field you cannot save.

How __MSG_ in the manifest reaches your AMO name

The add-on name is the one listing field with a direct wire back into your extension package. You localize it the same way you localize any manifest string — with a __MSG_ placeholder resolved from _locales. MDN’s WebExtensions internationalization guide gives the pattern:

// manifest.json
{
  "manifest_version": 3,
  "name": "__MSG_extensionName__",
  "description": "__MSG_extensionDescription__",
  "default_locale": "en"
}

with the values living one per locale:

// _locales/de/messages.json
{
  "extensionName": {
    "message": "Tab-Manager",
    "description": "Name shown in the browser and on AMO"
  },
  "extensionDescription": {
    "message": "Gruppiert offene Tabs automatisch nach Domain.",
    "description": "Short manifest description"
  }
}

MDN documents the placeholder syntax precisely — two underscores, the literal string MSG, one underscore, the message name, two underscores — and states that default_locale “specifies a default locale to use if the extension doesn’t include a localized string for the browser’s current locale.” Our __MSG_ keys in manifest.json guide covers the placeholder mechanics in depth, and Firefox WebExtensions i18n and messages.json covers the runtime side.

Does AMO auto-detect locales from _locales?

Mozilla’s published developer documentation does not answer this, so we read the source. AMO runs on addons-server, which is open source. As of 8 August 2026, the code on master does the following when an upload creates a new add-on record:

The bare-code expansions in that second step are worth knowing, because a Chrome _locales tree is full of bare codes:

_locales folder  →  AMO locale
  en             →  en-US
  es             →  es-ES
  pt             →  pt-PT
  sv             →  sv-SE
  zh             →  zh-CN
  ga             →  ga-IE
  pt_BR          →  pt-BR   (underscore → hyphen)
  zh_TW          →  zh-TW   (underscore → hyphen)

Two things this seeding step does not do, and both matter. It does not fill in your long listing description, screenshots, screenshot captions or tags — those are listing-only content that never existed in your package. And it runs on the code path that creates the add-on record, so it is not a substitute for maintaining your listing text afterwards. Once the listing exists, the Developer Hub is authoritative.

The per-locale Developer Hub workflow

Mozilla does not publish step-by-step instructions for adding a localized listing, and AMO’s Developer Hub UI has changed over the years, so we are not going to invent button labels for you. What we can describe is the shape of the form and the rules it enforces, both of which are visible in addons-server.

The listing edit form — the one Mozilla calls the Describe step — declares name, summary and description as translatable fields. Translatable fields render a per-locale editor rather than a single text box: you pick a locale and enter the value for that locale, and the stored value is a map from locale code to string, not one string. Slug, support URL and support email are plain single-value fields on the same form.

The one hard rule the form enforces is about your default locale. If you try to change it, AMO checks that the three core fields already exist in the new locale and refuses otherwise, with this message:

Before changing your default locale you must have a name, summary, and description in that locale. You are missing ‘description’.

Which is a good rule, and a good reminder of the underlying model: your listing has one default locale that everything falls back to, and any number of overriding locales layered on top. Missing a locale is not an error state. It just means users in that language read your default-locale copy — the same fallback behaviour you already rely on for default_locale in the manifest.

The field lengths defined in addons-server as of 8 August 2026:

Only the 250-character summary limit is stated in Mozilla’s developer documentation. The other two are read from the addons-server model definitions and could change without a docs update — treat them as working budgets, not contract.

Mozilla does not translate your listing for you

This surprises people, because Firefox itself is one of the most thoroughly localized pieces of software on the planet and Mozilla runs a translation platform called Pontoon. None of that reaches your add-on. From the Mozilla Add-ons Community Blog, “No longer lost in translation”, published 16 July 2018:

At present, we don’t have a way to connect extension developers with the translation community at scale, and Pontoon, Mozilla’s tool for localizing products and websites, currently only supports translating the AMO site itself.

That post describes a one-off volunteer campaign: more than 100 multilingual Mozillians submitted over 140,000 translated words through Crowdin, covering 9 extensions in 7 languages. Impressive, and also the shape of the problem — a campaign, run once, for nine extensions.

A workflow that scales

The failure mode is not translation quality. It is that listing copy lives in a web form, drifts out of sync with the copy in your repository, and nobody can tell you what the current Polish summary says without logging in. Keep the source of truth in version control:

Chrome Web Store has the same per-language listing problem and the same lack of bulk upload; if you also ship to Chrome, the console script for automating CWS listing translations removes most of the copy-paste there. Edge is a different story again — its Partner Center reads your _locales folder to decide which listing languages even exist, which produces a memorable failure mode covered in localizing your Edge Add-ons listing.

Locale codes: one tree, three stores

A single _locales folder feeds Chrome, Firefox and Edge, but the three do not agree on how to spell a locale. Chrome’s folder convention uses underscores (pt_BR); AMO normalises to hyphens internally (pt-BR); the Chrome Web Store dashboard has its own quirks, including iw for Hebrew.

The rule that keeps this manageable: name your folders the Chrome way. Underscores, exact casing, codes from Chrome’s supported list. That tree loads in Firefox, loads in Chrome, and is what Edge’s Partner Center scans. The stores normalise inbound; none of them will fix a folder name that was invalid to begin with. See Chrome extension locale codes for the full list and the codes that look right but are not.

Frequently asked questions