# Manifest localization: lang, dir, and *_localized members

> How the Web App Manifest's dir and lang members set default text direction and language, and how the *_localized member pattern (name_localized, short_name_localized, description_localized, icons_localized) provides per-field translations with locale fallback.

**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:

```json
{
  "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):

```json
{
  "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.