*_localized

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The _localized suffix is added to manifest members to create localized variants of those members. The browser will use the variant that best suits the user based on their browser language settings.

Syntax

json
/* Localized text values */
"member_localized": {
  "lang1": text_l10n,
  "lang2": text_l10n,
  "langN": text_l10n,
}

/* Localized icon resources */
"member_localized": {
  "lang1": icon_l10n,
  "lang2": icon_l10n,
  "langN": icon_l10n,
}

Values

member_localized

An object specifying localized member variants. For example, name_localized would specify localized variants for the name field.

lang1 ... lang2 ... langN

Each object contains one or more properties with keys equal to a BCP 47 language tag representing a language to provide a variant for. The property values can be one of two types:

text_l10n

An object or a string containing a text localization; see text localization.

icon_l10n

An array of objects containing references to localized icon resources; see icon localization.

Text localization

When the localized variant provides a localization of a text value, the property values can be objects or strings.

The object representation can have the following properties:

value

A string containing the localized text.

dir Optional

A string representing the text direction of the localized text. Valid values of dir are:

auto

The default. Specifies that the text direction is unknown. The direction will be inferred from the browser's language settings.

ltr

Specifies a left-to-right text direction.

rtl

Specifies a right-to-left text direction.

lang Optional

A string containing a BCP 47 language tag representing a locale for the localized text.

In most cases, the shorthand string representation can be used, which contains the localized text value. The object form is only needed in cases where you want to specify a different text direction to the default browser language, or the localized text needs to be presented in a different language from the user's locale.

Icon localization

The icons_localized member object property values are arrays containing one or more objects representing localized icon choices.

Each object contains the same properties as the non-localized icons member: src, sizes, type, and purpose.

Shortcut localization

The shortcuts member can be localized, but this is not done by specifying a shortcuts_localized member. Instead, you provide *_localized versions of the name, short_name, description, and icons members nested inside the shortcut member.

Description

The _localized suffix is used to create localized manifests.

You can add the _localized suffix to a supporting manifest member to create localized variants of that member. The browser will use the variant that best suits the user based on their browser language settings. Each property of a localized variant has a key equal to a BCP47 language tag representing the locale language, and a value that represents the localized variant.

If one of the keys matches the user's browser language setting, that variant will be used. If not, the non-prefixed manifest member value will be used.

Note: In cases where multiple related language variants are specified, the browser matches more granular language tags first, before falling back to more general tags. For example, if the user's browser language is set to fr-CA, it'll look for a variant with the fr-CA language tag first, then fall back to an fr variant if fr-CA is not available. If neither are available, it will fall back to the non-localized value. See Localize an app manifest for an example.

Members for which localized variants are supported (both at the manifest top level, and inside the shortcuts member):

Localized text

Localized text field properties have values equal to objects or strings; the string form is by the far the most common.

For example:

json
{
  ...
  "name": "The SuperSausage sausage app",
  "name_localized": {
    "fr": "L'application de saucisse SuperSausage",
    "de": "Die SuperWurst-App",
    "ur":  "سپر ساسیج ساسیج ایپ",
    "ja": "スーパーソーセージのソーセージアプリ"
  }
  ...
}

If the user has their browser language set to fr, de, ur, or ja, the browser will use the appropriate name found in the name_localized member for that language as the app's name. If not, the browser will use the name found in the name member.

Sometimes you will want to specify a different lang value inside a localized variant to the actual language of that variant. For example:

json
}
  ...
  "short_name": "SuperSausage",
  "short_name_localized": {
    "fr": {
      "lang": "en-US",
      "value": "Sausage Super"
    },
    "de": "SuperWurst",
    "ur": "سپر ساسیج",
    "ja": "スーパーソーセージ"
  },
  ...
}

In this case, our French audience knows our app by a variant of the English brand name — "Sausage Super" — and we want to specify that this should be handled as English rather than French (for example, for the purposes of pronunciation). This is done by specifying a lang value of en-US inside the variant.

Localized icons

A localized icons set consists of an object containing multiple arrays, each one containing objects representing the icon choices for a different locale:

json
{
  "icons": [
    {
      "src": "./icons/icon-128.png",
      "sizes": "128x128",
      "type": "image/png"
    }
  ],
  "icons_localized": {
    "de": [
      {
        "src": "./icons/localized_icons/de/icon-128.png",
        "sizes": "128x128",
        "type": "image/png"
      }
    ],
    "ar": [
      {
        "src": "./icons/localized_icons/ar/icon-128.png",
        "sizes": "128x128",
        "type": "image/png"
      }
    ],
    "fr": [
      {
        "src": "./icons/localized_icons/fr/icon-128.png",
        "sizes": "128x128",
        "type": "image/png"
      }
    ]
  }
}

If the user has their browser language set to de, ar, or fr, an appropriate entry from the icons_localized member will be used. If not, the icon referenced in the icons member will be used.

Each localized icons array is treated as completely independent from all the others. If an icons variant matches the user's browser language setting, only icons from within that variant will be chosen for that user. For example, if you have 20 icons specified inside icons, and only one icon specified inside icons_localized.fr, users with fr set as their browser's language will only ever see one icon used everywhere. The browser won't look inside the icons array for more suitable sizes.

Localized shortcuts

Localized shortcut sub-members are provided inside the shortcuts member.

For example:

json
"shortcuts": [
  {
    "name": "Open dashboard",
    "name_localized": {
      "en": "Open dashboard",
      "de": "Dashboard öffnen",
      "ar": "فتح لوحة المعلومات"
    },
    "short_name": "Dashboard",
    "short_name_localized": {
      "en": "Dashboard",
      "de": "Dashboard",
      "ar": "لوحة"
    },
    "description": "Go to your dashboard.",
    "description_localized": {
      "en": "Go to your dashboard.",
      "de": "Zum Dashboard wechseln.",
      "ar": "انتقل إلى لوحتك."
    },
    "url": "./dashboard",
    "icons": [
      { "src": "./icons/shortcut-dashboard.png", "sizes": "96x96", "type": "image/png", "purpose": "any" }
    ],
    "icons_localized": {
      "en": [
        { "src": "./icons/icon-128.png", "sizes": "128x128", "type": "image/png", "purpose": "any" }
      ],
      "de": [
        { "src": "./icons/localized_icons/de/Iconka-Meow-Cat-purr.128.png", "sizes": "128x128", "type": "image/png", "purpose": "any" }
      ],
      "ar": [
        { "src": "./icons/localized_icons/ar/black_cat-128.png", "sizes": "128x128", "type": "image/png", "purpose": "any" }
      ]
    }
  }
],

Examples

For examples, check out;

Specifications

See also