Manifest localization: lang, dir, and *_localized members

In one line: The manifest spec defines dir and lang to set a default text direction and language for the manifest’s localizable members, and a *_localized member pattern (name_localized, short_name_localized, description_localized, icons_localized) to supply per-language translations with automatic fallback. There is no single member literally named translations — per-field translation is what the *_localized pattern provides.

dir: default text direction

dir is a string restricted to "ltr" (left-to-right), "rtl" (right-to-left), or "auto" (default — the user agent estimates direction when it is unknown). Per the spec, it “specifies the default direction for the…localizable members of the manifest.” If the member is absent or its value is invalid, the processing algorithm sets it to "auto".

lang: default language

lang is a string language tag that “specifies the language for the values of the manifest’s…localizable members.” If omitted, the language is treated as unknown. The value must be a well-formed Language-Tag per BCP47 (e.g. fr, en-AU, zh-Hans-CN); language tags are case-insensitive.

MDN’s manifest reference notes that, as implemented today, dir, lang, and iarc_rating_id are not implemented by browsers.

*_localized: per-field translations

Each localizable manifest member has a corresponding *_localized member — name_localized, short_name_localized, description_localized, and icons_localized — keyed by BCP 47 language tag:

{
  "name": "The SuperSausage sausage app",
  "name_localized": {
    "fr": "L'application de saucisse SuperSausage",
    "de": "Die SuperWurst-App"
  }
}

A localized text value can be a plain string, or an object with a required value and optional dir/lang overrides (used when a translation’s direction or language differs from what the key would imply — e.g. keeping an English brand name for French users):

{
  "short_name_localized": {
    "fr": { "lang": "en-US", "value": "Sausage Super" },
    "de": "SuperWurst"
  }
}

icons_localized maps each language tag to its own array of icon objects (same shape as icons: src, sizes, type, purpose). Each localized icon array is independent — the browser does not supplement it with entries from the base icons array.

shortcuts has no top-level shortcuts_localized member; instead, name_localized/short_name_localized/description_localized/icons_localized are nested inside each individual shortcut object.

Locale matching and fallback

Per the spec, the user agent should select whichever localized value best matches the user’s preferred locale(s), and falls back to the non-localized base member (name, short_name, description, icons) when no localized value is available. The spec does not mandate a specific tag-matching algorithm (e.g. most-specific-first with stepwise fallback to broader tags).

Implementation status

MDN’s *_localized reference marks the pattern experimental, directing readers to check browser compatibility data before relying on it in production. dir and lang are explicitly called out as not implemented.

Practical checklist

• Do not rely on dir/lang alone for direction/language control — MDN notes neither is implemented.
• Use *_localized members for per-field translations; keep the base name / short_name / description / icons as the fallback for unmatched locales.
• Supply full icon sets in every icons_localized language entry you provide — the browser will not merge in icons from the base icons array.
• For shortcuts, nest *_localized members inside each shortcut object; there is no shortcuts_localized.
• Check current browser compatibility data before depending on *_localized in production, since MDN marks it experimental.

Specifications

Specification	Status
None.