Technical review: Document web app manifest localization

[chrisdavidmills]

Description

Chrome and Edge 148 desktop have added support for *_localized members, aka localizable web app manifests. See https://chromestatus.com/feature/5090807862394880.

This PR adds reference documentation for *_localized members and the dir and lang members, as well as a how-to guide covering how to localize a web app manifest.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs (4 pages)

• /en-US/docs/Web/Progressive_web_apps/How_to/Localize_an_app_manifest
• /en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized
• /en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir
• /en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang

External URLs (4)

URL: /en-US/docs/Web/Progressive_web_apps/How_to/Localize_an_app_manifest
Title: Localize an app manifest

• https://developer.chrome.com/blog/manifest-localization (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized
Title: *_localized

• https://developer.chrome.com/blog/manifest-localization (1 time) (Note! This may be a new URL 👀)
• https://github.com/MicrosoftEdge/Demos/tree/main/pwa-manifest-localization/ (1 time) (Note! This may be a new URL 👀)
• https://microsoftedge.github.io/Demos/pwa-manifest-localization/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-07-09 16:21:28)

[hamishwillee]

This doesn't quite work because the French Canadian version doesn't need its direction set either.

[chrisdavidmills]

I've chatted to @kyerebo about the dir and lang members' involvement in manifest localization, and ... they are confusingly not involved at all. I've therefore made quite a few changes to the articles.

In this particular case (and on the dir page), I've cut the example right down, removing all this stuff.

[hamishwillee]

How does this work - i.e this is fr, but you also have a lang that is "fr-CA". However I know lang sets the default language.

My guess is that this should omit lang and fix up the key.

    "fr-CA": { "value": "Sélecteur de Couleur", "dir": "ltr" },

Further, in the intro it says "will see the app's name displayed in a more suitable language for them."

I would like to understand the fallback here. If my language is set to fr, will it choose "fr-CA" or will it choose English ? Can I declare both "fr" and "fr-CA", and so on. The example could show a case or two.

[hamishwillee]

Also see https://github.com/mdn/content/pull/44609/changes#r3517444725

[hamishwillee]

Definitely see https://github.com/mdn/content/pull/44609/changes#r3517481036 :-)

[kyerebo]

I can't speak to the standards approach to this, but for the Chromium implementation, the localized member's lang field, if specified, doesn't currently have an effect on what the user sees.
The primary criteria for localization selection is if there exists a language tag that matches or partly matches the user's current browser language setting.

So if we had something like:

"fr": { "value": "Color Selector, "lang": "en" },

The end result for a browser set to French is that we'd see Color Selector.
The lang field is effectively acting as a "heads up, this value is this language rather than the one specified by the language tag."

[chrisdavidmills]

Again, I've cut this right down. In other places, I've made the text more understandable.

In the particular case of the lang property being different from the main object property key, I've removed the fr-CA example and used a much more obvious one; see the Howto guide's short_name_localized example.

[hamishwillee]

Is there a default lang assumed?

[kyerebo]

I think including the manifest-level dir and lang as part of this conversation can be confusing.
In the Chromium implementation, the language selection is independent of the manifest-level lang specification, and is solely based on the user's browser language.

[chrisdavidmills]

I've updated this. The chosen language has nothing to do with lang. When localized members are included (e.g. name_localized), the browser chooses the variant that matches the user's browser language setting.

If no variant matches the user's browser language setting, the value in the non-localized member is used instead (e.g. name). I've explained this in the *_localized reference and the Howto.

[hamishwillee]

Same comments as for the lang case.

Note also that this is a dir topic. I'd show a screen shot or explicitly state at least somewhere that the text will be drawn LTR and show it.

[chrisdavidmills]

Again, this is all now cut down and changed around.

[hamishwillee]

How do I localise the rest of the app? We should at least mention that (or if it can't be done, state that too). I assume perhaps we can specify a key for the default language entry point?

[chrisdavidmills]

Localizing the rest of the app is a huge topic and out of scope for this article. How you would go about localizing it depends on what kind of app it is, what stack you've used, etc.

https://github.com/oh-jon-paul/awesome-i18n gives you an idea of what's available.

[hamishwillee]

1. What if I don't set a default language or dir, what is used?

2. While I understand exactly what you mean, this doesn't feel quite right

   These will be assumed by the browser if no language and direction more suitable for the user's preferences are found in the *_localized variants.

   It's because the languages will be used but it isn't lang and dir that will be used. What will be used is the other non-localized members. You clarify this in the next sentence, but "These" still grates.

[kyerebo]

1. At least in the Chromium implementation, if no dir is specified for a localized member, it uses the direction of the browser's currently set language. Localizations are selected based off of the browser's currently set language at all times.

[chrisdavidmills]

See previous comments.

[hamishwillee]

I'm nearing the end of my review, and I realize that this first doc that I read in the review is confusing:

overriden by a different lang value found in a *_localized member.

If it specifies the default language for my web application, what sense does it make to override?

[chrisdavidmills]

See previous comments.

[hamishwillee]

See https://github.com/mdn/content/pull/44609/changes#r3517481036 - lang in a translation needs additional explanation there. I think I get it now, finally on this the second last doc - this allows you to specify that the value from some other language key should be used for a translation, instead of providing your own, or using the default?

Typo too

Suggested change

	The French (`fr`) `short_name` translation shows typical usage of the object value form being used to specify a `lang` property. In this case, our French audience knows our app by its English brand name — "SuperSausage" — and we want to specify that this should be handled as English rather than French (for example, for the purposes of pronounciation).
	The French (`fr`) `short_name` translation shows typical usage of the object value form being used to specify a `lang` property. In this case, our French audience knows our app by its English brand name — "SuperSausage" — and we want to specify that this should be handled as English rather than French (for example, for the purposes of pronunciation).

[kyerebo]

I'm reading it as clarification that although the localized object is under the French language tag, the value of the object is presented in English rather than French.

From the web application manifest spec:

To support multilingual content and ensure optimal display and accessibility, it is possible to specify a different language for a localized text object. This is needed for situations where a term or text needs to be presented in a language different from the user's set locale.

[chrisdavidmills]

see above

[chrisdavidmills]

I've fixed the typo

[hamishwillee]

I think you need your shortcuts - I want to know how to select my language version.

[chrisdavidmills]

Do you mean you want me to include a shortcuts example?

[hamishwillee]

Suggested change

	in this example, the app's default `en-US` language `name` is "Color picker", but we've also specified localized variants in the `name_localized` member. Users that have their primary language preference set to German (`de`), French (`fr`), or Arabic (`ar`) will see the app's name displayed in a more suitable language for them.
	In this example, the app's default `en-US` language `name` is "Color picker", but we've also specified localized variants in the `name_localized` member. Users that have their primary language preference set to German (`de`), French (`fr`), or Arabic (`ar`) will see the app's name displayed in a more suitable language for them.

[hamishwillee]

But also see my other comment on lang - this could be better worded.

[chrisdavidmills]

this is changed now

[hamishwillee]

It isn't clear why the French version needs a lang and dir and the german version does not - same thing as https://github.com/mdn/content/pull/44609/changes#r3517444725

Somewhere else, perhaps in the how to, you indicate that lange in a localized member takes a language from somewhere else. So here you're saying that for French ou take your language from "fr-CA". But then there are two more questions:

• If you are taking it from fr-CA, where is your fr-CA definition?
• If you are taking it from fr-CA, why do you have a value?

I suspect the answer might be "take it from fr-CA if defined and otherwise fall back to the specified value. But that feels like poor design to me.

[kyerebo]

Agreed, neither of these actually need dir or lang specified, those are always optional fields.

The manifest spec is actually pretty loose on what lang for localized members should do beyond "specifying when it should be presented as another language".
At least in the Chromium implementation, for current cases that make localized members user-visible, it seems to ignore the lang field if provided.

[chrisdavidmills]

I've changed this for a more obvious example

[hamishwillee]

Is it icons or image or both? If it can only be icons we should say that. If icons and other images are different we should say that. We should also note "somewhere" whether the localised set can have diferrent sets of icons or must match the same sizes

[kyerebo]

+1 let's change this to "Localized icons"

The localized set can have different sets of icons; each localization is treated independently as if the other localizations didn't exist.

[chrisdavidmills]

I've changed it to "icons"

[kyerebo]

Mostly comments about clarifying the effect of manifest-level lang and dir, thanks!

[kyerebo]

Touched upon this in email with Chris, reposting here in more detail.
The dir and lang manifest-level members are somewhat independent of the localization feature.
*_localized members are selected based off of the browser's language setting, not off of the other manifest members.
This is definitely a bit confusing in the spec, as it says the manifest-level dir/lang set the default value of localized members, but the section on localized members clarifies that the default representation is the manifest member without *_localized and localizations should be selected based off of the user's language setting.
The manifest-level dir is defined in the spec as applying a default text direction for localized members that are missing a dir field, but the Chromium implementation only prioritizes whatever direction is specified by the localized member.
The manifest-level lang field isn't actually used when calculating which localized value to show.

In practice (or at least how it works right now in Chromium), this means that the manifest-level lang and dir don't have implications for the localized value that ends up getting chosen. Perhaps we can remove or edit the references to these manifest level members to avoid confusing developers?
The suggested instructions for working with localizable manifests on the chrome developer blog don't mention manifest-level dir or lang as any sort of fallback.

[chrisdavidmills]

I think I've captured this all in my updates, except maybe this bit:

The manifest-level dir is defined in the spec as applying a default text direction for localized members that are missing a dir field, but the Chromium implementation only prioritizes whatever direction is specified by the localized member.

But I'm not sure if there is really much worth saying.

[kyerebo]

I agree it's probably not worth specifying. LGTM.

[kyerebo]

Consider removing/editing this section as part of comment above.

[chrisdavidmills]

done

[kyerebo]

1. At least in the Chromium implementation, if no dir is specified for a localized member, it uses the direction of the browser's currently set language. Localizations are selected based off of the browser's currently set language at all times.

[kyerebo]

I'm reading it as clarification that although the localized object is under the French language tag, the value of the object is presented in English rather than French.

From the web application manifest spec:

To support multilingual content and ensure optimal display and accessibility, it is possible to specify a different language for a localized text object. This is needed for situations where a term or text needs to be presented in a language different from the user's set locale.

[kyerebo]

Maybe it makes sense to break out shortcut localization to its own section. Localization of shortcuts looks a little different than described here. Rather than shortcuts having a corresponding *_localized version, it's that shortcut fields can be localized.

An example from this test site:

 "shortcuts": [
    {
      "name": "Open Dashboard",
      "name_localized": {
        "en": { "value": "Open Dashboard", "lang": "en", "dir": "ltr" },
        "de": { "value": "Dashboard öffnen", "lang": "de", "dir": "ltr" },
        "ar": { "value": "فتح لوحة المعلومات", "lang": "ar", "dir": "rtl" }
      },
      "short_name": "Dashboard",
      "short_name_localized": {
        "en": { "value": "Dashboard", "lang": "en", "dir": "ltr" },
        "de": { "value": "Dashboard", "lang": "de", "dir": "ltr" },
        "ar": { "value": "لوحة", "lang": "ar", "dir": "rtl" }
      },
      "description": "Go to your dashboard.",
      "description_localized": {
        "en": { "value": "Go to your dashboard.", "lang": "en", "dir": "ltr" },
        "de": { "value": "Zum Dashboard wechseln.", "lang": "de", "dir": "ltr" },
        "ar": { "value": "انتقل إلى لوحتك.", "lang": "ar", "dir": "rtl" }
      },
      "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" }
        ]
      }
    }
  ],

[chrisdavidmills]

OK, I think I've made all the updates I need, except for more coverage of shortcuts. I'll work on that tomorrow.

[kyerebo]

Agreed, neither of these actually need dir or lang specified, those are always optional fields.

The manifest spec is actually pretty loose on what lang for localized members should do beyond "specifying when it should be presented as another language".
At least in the Chromium implementation, for current cases that make localized members user-visible, it seems to ignore the lang field if provided.

[kyerebo]

+1 let's change this to "Localized icons"

The localized set can have different sets of icons; each localization is treated independently as if the other localizations didn't exist.

[kyerebo]

Typo "specfiied"

[chrisdavidmills]

This is all changed now.

[kyerebo]

I think including the manifest-level dir and lang as part of this conversation can be confusing.
In the Chromium implementation, the language selection is independent of the manifest-level lang specification, and is solely based on the user's browser language.

[kyerebo]

I can't speak to the standards approach to this, but for the Chromium implementation, the localized member's lang field, if specified, doesn't currently have an effect on what the user sees.
The primary criteria for localization selection is if there exists a language tag that matches or partly matches the user's current browser language setting.

So if we had something like:

"fr": { "value": "Color Selector, "lang": "en" },

The end result for a browser set to French is that we'd see Color Selector.
The lang field is effectively acting as a "heads up, this value is this language rather than the one specified by the language tag."

[kyerebo]

Thanks for making those changes, the new technical descriptions LGTM.