Skip to content

Manifest member in Manifest

lang, dir, and *_localized manifest members

Published

The lang and dir manifest members declare the language and writing direction of text members. Use *_localized members (name_localized, short_name_localized, description_localized, icons_localized) to provide variants keyed by BCP 47 language tag, with the plain member as the fallback. Localization is per field; there is no single translations member.

Chrome 148 and Edge 148 read the *_localized members for name, short_name, description, icons, and the same four fields inside each shortcuts entry (developer.chrome.com, manifest localization announcement). MDN records dir and lang as not implemented by any browser as top-level members; Chromium reads the lang and dir overrides inside a localized value. Firefox 157 and Safari 27 drop every *_localized member and show the plain name.

Member Type and values Default and invalid values
lang String containing a BCP 47 language tag, such as en-AU or zh-Hans-CN, compared case-insensitively Unset: the language is unknown. An ill-formed tag is dropped.
dir String: ltr, rtl, or auto auto estimates direction from the text. An unrecognized value resolves to auto.
*_localized Object keyed by language tag. Text values are strings or objects of the form { "value": "...", "lang": "...", "dir": "..." }. Each icons_localized value is a complete icon array in the shape of icons. Absent: the plain member is used for every language.

Example value: "name_localized": { "de": "Farbwähler", "en-GB": { "value": "Colour Picker" } }.

Matching picks the entry that best fits the browser’s language list and falls back to the plain member when nothing matches; the specification leaves the exact tag-matching algorithm to the browser. A localized icon array replaces icons wholesale for that language, it is not merged with it, so every language entry needs its full set of sizes. shortcuts has no shortcuts_localized; the four *_localized members nest inside each shortcut object instead.

A text *_localized member that is not an object is dropped without a message, and the plain member keeps working. A non-object icons_localized is dropped with property 'icons_localized' ignored, type object expected.

The plain name and description are the fallback for languages without a localized entry.

Localizing the name and description with a plain-member fallback

Section titled “Localizing the name and description with a plain-member fallback”

lang and dir describe those plain values, so a German-first app sets lang to de and puts the English text under name_localized.en.

{
"lang": "de",
"dir": "ltr",
"name": "Farbwähler",
"description": "Farben aus Bildern auswählen und als Palette speichern.",
"name_localized": {
"en": "Color Picker",
"en-GB": "Colour Picker",
"fr": "Sélecteur de couleur"
},
"description_localized": {
"en": "Pick colors from images and save them as a palette."
}
}

A browser set to en-US gets Color Picker from the en entry; one set to en-GB gets the more specific spelling; one set to Spanish falls back to the German plain value, which is the cue to add an es entry.

Keeping a brand name in English for a right-to-left locale

Section titled “Keeping a brand name in English for a right-to-left locale”

A value object carries its own lang and dir when they differ from what the key implies. Here the Arabic entry keeps the Latin brand name and marks it as left-to-right English inside a right-to-left manifest.

{
"lang": "ar",
"dir": "rtl",
"name": "منتقي الألوان",
"short_name_localized": {
"ar": { "value": "ColorPick", "lang": "en", "dir": "ltr" },
"en": "ColorPick"
}
}

Without the per-value dir, a bidirectional renderer may place the Latin label incorrectly beside Arabic text in the launcher; the override is the fix the spec provides for exactly this.

Shipping localized icons and checking what the browser resolved

Section titled “Shipping localized icons and checking what the browser resolved”

Icons with embedded text need a per-language array. The script then reads the manifest and reports which entry the browser will pick for its own language, with a fallback to the plain icons when no entry matches, which is also what a browser without *_localized support does.

{
"icons": [{ "src": "/icons/en-512.png", "sizes": "512x512", "type": "image/png" }],
"icons_localized": {
"ja": [{ "src": "/icons/ja-512.png", "sizes": "512x512", "type": "image/png" }]
}
}
async function resolvedIcons() {
const link = document.querySelector('link[rel="manifest"]');
if (!link) return [];
const manifest = await fetch(link.href).then((r) => r.json());
const localized = manifest.icons_localized ?? {};
const tag = navigator.languages.find((l) => localized[l] || localized[l.split('-')[0]]);
if (!tag) return manifest.icons ?? []; // no match or no support: plain icons
return localized[tag] ?? localized[tag.split('-')[0]];
}

The function implements the fallback rule but does not reproduce the browser’s exact tag-matching algorithm. Use its output as a settings-page preview; it cannot guarantee which icon the OS will show.

Specifications

SpecificationStatus
Web Application Manifest: lang memberW3C
Web Application Manifest: dir memberW3C