From 026f7d440dc295cc3937a6d3a7259e5a7d086a9d Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Tue, 30 Jun 2026 16:54:30 +0100 Subject: [PATCH 01/12] Document web app manifest localization --- .../how_to/localize_an_app_manifest/index.md | 279 ++++++++++++++++++ .../reference/_star__localized/index.md | 170 +++++++++++ .../manifest/reference/dir/index.md | 64 ++++ .../manifest/reference/lang/index.md | 57 ++++ files/sidebars/pwasidebar.yaml | 1 + 5 files changed, 571 insertions(+) create mode 100644 files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md create mode 100644 files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md create mode 100644 files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md create mode 100644 files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md new file mode 100644 index 000000000000000..fb4372dcb81f220 --- /dev/null +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -0,0 +1,279 @@ +--- +title: Localize an app manifest +slug: Web/Progressive_web_apps/How_to/Localize_an_app_manifest +page-type: how-to +sidebar: pwasidebar +--- + +[Progressive Web App (PWA)](/en-US/docs/Web/Progressive_web_apps) manifests can be localized using a combination of the [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) manifest member suffix, the [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) member, and the [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) member. + +Manifest localization allows the browser to choose between different text strings (for app names and descriptions, for example) and icons when loading the app to best suit the user's language preferences. + +This guide shows how to localize a PWA manifest, using the following example as a starting point: + +```json +{ + "name": "The SuperSausage sausage app", + "short_name": "SuperSausage", + "description": "Find information on all your favorite sausages!", + "start_url": "./", + "display": "standalone", + "background_color": "#ffffff", + "theme_color": "#ab510d", + "icons": [ + { + "src": "./icons/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ] +} +``` + +## Set a default language and direction + +The [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) and [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) members define a default language and language direction for the app. These will be assumed by the browser if no language and direction more suitable for the user's preferences are found in the [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) variants. In such cases, the non-prefixed members are used (for example, `name`). + +Set a suitable default language and direction like so: + +```json +"lang": "en-US", +"dir": "ltr" +``` + +## Choose the manifest members you want to localize + +The following members support localized variants: + +- [`name`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/name) +- [`short_name`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/short_name) +- [`description`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/description) +- [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) +- [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts) + +Our sample manifest has all of these except for `shortcuts`; we'll show how to localize each one. + +## Choose the languages you want to support + +Generally you should support all of the languages relevant to your major target audience locales. + +For this example, we'll choose French (`fr`), German (`de`), Urdu (`ur`), and Japanese (`ja`). + +## Localizing the `name` member + +Localized versions of the `name` member are contained in the `name_localized` member. Each property inside `name_localized` has to have a key equal to one of the target language's {{glossary("BCP 47 language tag", "BCP 47 language tags")}}, and a value equal to an object or a string representing the localized text for that language. + +Let's see what this could look like for our example: + +```json +"name_localized": { + "fr": "L'application de saucisse SuperSausage", + "de": "Die SuperWurst-App", + "ur": { + "dir": "rtl", + "value": "سپر ساسیج ساسیج ایپ" + }, + "ja": "スーパーソーセージのソーセージアプリ" +} +``` + +In this case, we've used the string form for all the languages, except for Urdu, which uses the object form. This is because Urdu is an RTL language — we have specified a `dir` value of `rtl` for it, so that browsers will display it correctly. + +## Localizing the other text-based members + +We can follow the same pattern as we did for the `name` member to localize the `short_name` and `description` members: + +```json +"short_name_localized": { + "fr": { + "lang": "en-US", + "value": "SuperSausage" + }, + "de": "SuperWurst", + "ur": "سپر ساسیج", + "ja": "スーパーソーセージ" +}, +"description_localized": { + "fr": "Trouvez des informations sur toutes vos saucisses préférées !", + "de": "Finden Sie Informationen zu all Ihren Lieblingswürstchen!", + "ur": "اپنی تمام پسندیدہ ساسیجز کے بارے میں معلومات حاصل کریں!", + "ja": "お気に入りのソーセージの情報を全部見つけましょう!" +}, +``` + +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). + +## Localizing the `icon` member + +The `icon` localization is covered in a separate section because localized images are handled somewhat differently to localized text. The properties of each `*_localized` member (`icon_localized`, in this case) are equal to an array of objects containing the same properties as the non-localized original (`icon`); each one provides details for a localized image. + +Let's see what this looks like: + +```json +"icons_localized": { + "fr": [ + { + "src": "./icons/l10n/fr/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/l10n/fr/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ], + "de": [ + { + "src": "./icons/l10n/de/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/l10n/de/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ], + "ur": [ + { + "src": "./icons/l10n/ur/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/l10n/ur/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ], + "ja": [ + { + "src": "./icons/l10n/ja/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/l10n/ja/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ], +} +``` + +## Finished manifest + +Putting this all together, the complete manifest looks like this: + +```json +{ + "name": "The SuperSausage sausage app", + "short_name": "SuperSausage", + "description": "Find information on all your favorite sausages!", + "start_url": "./", + "display": "standalone", + "background_color": "#ffffff", + "theme_color": "#ab510d", + "icons": [ + { + "src": "./icons/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ], + "lang": "en-US", + "dir": "ltr", + "name_localized": { + "fr": "L'application de saucisse SuperSausage", + "de": "Die SuperWurst-App", + "ur": { + "dir": "rtl", + "value": "سپر ساسیج ساسیج ایپ" + }, + "ja": "スーパーソーセージのソーセージアプリ" + }, + "short_name_localized": { + "fr": { + "lang": "en-US", + "value": "SuperSausage" + }, + "de": "SuperWurst", + "ur": "سپر ساسیج", + "ja": "スーパーソーセージ" + }, + "description_localized": { + "fr": "Trouvez des informations sur toutes vos saucisses préférées !", + "de": "Finden Sie Informationen zu all Ihren Lieblingswürstchen!", + "ur": "اپنی تمام پسندیدہ ساسیجز کے بارے میں معلومات حاصل کریں!", + "ja": "お気に入りのソーセージの情報を全部見つけましょう!" + }, + "icons_localized": { + "fr": [ + { + "src": "./icons/l10n/fr/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/l10n/fr/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ], + "de": [ + { + "src": "./icons/l10n/de/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/l10n/de/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ], + "ur": [ + { + "src": "./icons/l10n/ur/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/l10n/ur/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ], + "ja": [ + { + "src": "./icons/l10n/ja/saus-128.png", + "sizes": "128x128", + "type": "image/png" + }, + { + "src": "./icons/l10n/ja/saus-256.png", + "sizes": "256x256", + "type": "image/png" + } + ] + } +} +``` + +## See also + +- [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) manifest member +- [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) manifest member +- [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) manifest members +- [Localization support for web app manifests](https://developer.chrome.com/blog/manifest-localization) on developer.chrome.com (2026) diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md new file mode 100644 index 000000000000000..c10b623ea675dbf --- /dev/null +++ b/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md @@ -0,0 +1,170 @@ +--- +title: "*_localized" +slug: Web/Progressive_web_apps/Manifest/Reference/*_localized +page-type: web-manifest-member +browser-compat: manifests.webapp.localizable_members +sidebar: pwasidebar +--- + +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 language preferences. + +## Syntax + +```json-nolint +/* Localized text value */ +"member_localized": { + "lang1": text_l10n, + "lang2": text_l10n, + "langN": text_l10n, +} + +/* Localized image resource */ +"member_localized": { + "lang1": image_l10n, + "lang2": image_l10n, + "langN": image_l10n, +} +``` + +### Values + +- `member_localized` + - : An object specifying localized member variants. For example, `name_localized` would specify localized variants for the [`name`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/name) field. + - `lang1` ... `lang2` ... `langN` + - : Each object contains one or more properties with keys equal to a {{glossary("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](#text_localization). + - `image_l10n` + - : An array of objects containing references to localized image resources; see [image localization](#image_localization). + +#### Text localization + +When the localized variant is providing 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_inline}} + - : A string representing the text direction of the localized text, used in cases where the required direction of a localized string differs from the default direction set in the manifest (see [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir)). Valid values of `dir` are: + - `auto` + - : The default. Specifies that the text direction is unknown. The browser will use heuristics to estimate the display direction of the text. + - `ltr` + - : Specifies a left-to-right text direction. + - `rtl` + - : Specifies a right-to-left text direction. +- `lang` {{optional_inline}} + - : A string containing a BCP 47 language tag, used in cases where localized text needs to be presented in a different language from the user's locale. + +In cases where the `dir` and `lang` properties do not need to be specified, the shorthand string representation can be used. This consists of a string containing the localized text `value`. + +#### Image localization + +When the localized variant is providing a localization of an image resource, the property values are arrays containing one or more objects representing image choices. + +The exact properties contained within each object will be the same as the properties contained within the objects included with the non-localized versions of the members: + +- For `icons_localized`, the objects can have the same properties as the [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) member: `src`, `sizes`, `type`, and `purpose`. +- For `shortcuts_localized`, the objects can have the same properties as the [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts) member: `name`, `short_name`, `description`, `url`, and [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons). + +## Description + +The `_localized` suffix, along with the [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) and [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) members, are 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 language preferences. 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. + +Members for which localized variants are supported: + +- [`name`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/name) +- [`short_name`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/short_name) +- [`description`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/description) +- [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) +- [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts) + +### Localized text + +Localized text field properties have values equal to objects or strings. + +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. + +The French variant is specified as French Canadian (`fr-CA`) in its `lang` property, with a direction (`dir`) of `ltr`, while the Arabic variant has its `dir` specified as `rtl`. The German variant doesn't need its `lang` or `dir` specified, so its value is a string containing the localized text. + +```json +{ + "lang": "en-US", + "dir": "ltr", + "name": "Color Picker", + "name_localized": { + "de": "Farbwähler", + "fr": { "value": "Sélecteur de Couleur", "lang": "fr-CA", "dir": "ltr" }, + "ar": { "value": "`منتقي` `الألوان`", "dir": "rtl" } + } +} +``` + +The `lang` and `dir` members define a default language and language direction that will be assumed by the browser if no language more suitable for the user's preferences is found in the `name_localized` variants. In such cases, the `name` member is used. + +### Localized images + +A localized icon set will look like this: + +```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 specified a preference for German, Arabic, or French, an entry from the appropriate `icons_localized` member will be used. + +The `icons` member specifies the default icon that will be used if no language more suitable for the user's language preferences than the default `lang` is found in the `icons_localized` variants. + +## Examples + +For complete demos, check out; + +- The [PWA manifest localization demo](https://microsoftedge.github.io/Demos/pwa-manifest-localization/) app ([see source code](https://github.com/MicrosoftEdge/Demos/tree/main/pwa-manifest-localization/)). +- Our [Localize an app manifest](/en-US/docs/Web/Progressive_web_apps/How_to/Localize_an_app_manifest) How to guide. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) manifest member +- [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) manifest member +- [Localize an app manifest](/en-US/docs/Web/Progressive_web_apps/How_to/Localize_an_app_manifest) +- [Localization support for web app manifests](https://developer.chrome.com/blog/manifest-localization) on developer.chrome.com (2026) diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md new file mode 100644 index 000000000000000..424121a0b9637ce --- /dev/null +++ b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md @@ -0,0 +1,64 @@ +--- +title: dir +slug: Web/Progressive_web_apps/Manifest/Reference/dir +page-type: web-manifest-member +browser-compat: manifests.webapp.dir +sidebar: pwasidebar +--- + +The `dir` manifest member is used to specify a default language direction for your web application, which will be used unless overriden by a different `dir` value found in a [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) member. + +## Syntax + +```json-nolint +"dir": "auto" +"dir": "ltr" +"dir": "rtl" +``` + +### Values + +A string representing the app's text direction. Valid values of `dir` are: + +- `auto` + - : The default. Specifies that the text direction is unknown. The browser will use heuristics to estimate the display direction of the text. +- `ltr` + - : Specifies a left-to-right text direction. +- `rtl` + - : Specifies a right-to-left text direction. + +## Examples + +### Basic usage + +in this example, the app's default `lang` is `en-US`, and its default `dir` is `ltr`. Its default `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. + +The French variant is specified as French Canadian (`fr-CA`) in its `lang` property, with a direction (`dir`) of `ltr`, while the Arabic variant has its `dir` specified as `rtl`. The German variant doesn't need its `lang` or `dir` specified, so its value is a string containing the localized text. + +```json +{ + "lang": "en-US", + "dir": "ltr", + "name": "Color Picker", + "name_localized": { + "de": "Farbwähler", + "fr": { "value": "Sélecteur de Couleur", "lang": "fr-CA", "dir": "ltr" }, + "ar": { "value": "`منتقي` `الألوان`", "dir": "rtl" } + } +} +``` + +The `lang` and `dir` members define a default language and language direction that will be assumed by the browser if no language more suitable for the user's preferences is found in the `name_localized` variants. In such cases, the `name` member is used. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) manifest member +- [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) manifest members diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md new file mode 100644 index 000000000000000..26b3075c733671c --- /dev/null +++ b/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md @@ -0,0 +1,57 @@ +--- +title: lang +slug: Web/Progressive_web_apps/Manifest/Reference/lang +page-type: web-manifest-member +browser-compat: manifests.webapp.lang +sidebar: pwasidebar +--- + +The `lang` manifest member is used to specify a default language for your web application, which will be used unless overriden by a different `lang` value found in a [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) member. + +## Syntax + +```json-nolint +"lang": "en-US" +"lang": "ja" +"lang": "uk" +``` + +### Values + +a {{glossary("BCP 47 language tag")}} representing the app's default language. + +## Examples + +### Basic usage + +in this example, the app's default `lang` is `en-US`, and its default `dir` is `ltr`. Its default `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. + +The French variant is specified as French Canadian (`fr-CA`) in its `lang` property, with a direction (`dir`) of `ltr`, while the Arabic variant has its `dir` specified as `rtl`. The German variant doesn't need its `lang` or `dir` specified, so its value is a string containing the localized text. + +```json +{ + "lang": "en-US", + "dir": "ltr", + "name": "Color Picker", + "name_localized": { + "de": "Farbwähler", + "fr": { "value": "Sélecteur de Couleur", "lang": "fr-CA", "dir": "ltr" }, + "ar": { "value": "`منتقي` `الألوان`", "dir": "rtl" } + } +} +``` + +The `lang` and `dir` members define a default language and language direction that will be assumed by the browser if no language more suitable for the user's preferences is found in the `name_localized` variants. In such cases, the `name` member is used. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) manifest member +- [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) manifest members diff --git a/files/sidebars/pwasidebar.yaml b/files/sidebars/pwasidebar.yaml index 57250d2070e76d5..87c03b35fad0bf2 100644 --- a/files/sidebars/pwasidebar.yaml +++ b/files/sidebars/pwasidebar.yaml @@ -39,6 +39,7 @@ sidebar: - /Web/Progressive_web_apps/How_to/Expose_common_actions_as_shortcuts - /Web/Progressive_web_apps/How_to/Share_data_between_apps - /Web/Progressive_web_apps/How_to/Associate_files_with_your_PWA + - /Web/Progressive_web_apps/How_to/Localize_an_app_manifest - type: section link: /Web/Progressive_web_apps/Reference - /Web/Progressive_web_apps/Manifest From b7dca2497b6615ab23145c752b4e87f0ba0c0ff4 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 3 Jul 2026 08:59:59 +0100 Subject: [PATCH 02/12] Update files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md Co-authored-by: Hamish Willee --- .../web/progressive_web_apps/manifest/reference/lang/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md index 26b3075c733671c..8ba6a36fa9f0624 100644 --- a/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md +++ b/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md @@ -24,7 +24,8 @@ a {{glossary("BCP 47 language tag")}} representing the app's default language. ### Basic usage -in this example, the app's default `lang` is `en-US`, and its default `dir` is `ltr`. Its default `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 `lang` is `en-US` and default `dir` is `ltr`. +The default `name` is "Color picker", but we have also defined 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 their selected language. The French variant is specified as French Canadian (`fr-CA`) in its `lang` property, with a direction (`dir`) of `ltr`, while the Arabic variant has its `dir` specified as `rtl`. The German variant doesn't need its `lang` or `dir` specified, so its value is a string containing the localized text. From 3d14e5298a982301797856345d90b66a192025ab Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 3 Jul 2026 09:01:03 +0100 Subject: [PATCH 03/12] Update files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md Co-authored-by: Hamish Willee --- .../web/progressive_web_apps/manifest/reference/dir/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md index 424121a0b9637ce..30604a17a7a0e93 100644 --- a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md +++ b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md @@ -6,7 +6,8 @@ browser-compat: manifests.webapp.dir sidebar: pwasidebar --- -The `dir` manifest member is used to specify a default language direction for your web application, which will be used unless overriden by a different `dir` value found in a [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) member. +The `dir` manifest member is used to specify a default language directionality for your web application, which will be used unless overriden by a different `dir` value found in a [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) member. +If not specifies, the default direction is inferred from the default language, as specfiied using [`lang`]. ## Syntax From 30c38682faa74b56a646a17a4f518f218bd607cf Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 3 Jul 2026 09:03:27 +0100 Subject: [PATCH 04/12] Update files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md Co-authored-by: Hamish Willee --- .../web/progressive_web_apps/manifest/reference/dir/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md index 30604a17a7a0e93..2aea7f7df484c22 100644 --- a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md +++ b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md @@ -22,7 +22,7 @@ If not specifies, the default direction is inferred from the default language, a A string representing the app's text direction. Valid values of `dir` are: - `auto` - - : The default. Specifies that the text direction is unknown. The browser will use heuristics to estimate the display direction of the text. + - : The default. Specifies that the text direction is unknown. The browser will use heuristics to infer the display direction of the text. - `ltr` - : Specifies a left-to-right text direction. - `rtl` From 32f40cd3b5df87572b2580b233b5de9f446072a1 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 3 Jul 2026 09:09:29 +0100 Subject: [PATCH 05/12] Update files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md Co-authored-by: Hamish Willee --- .../how_to/localize_an_app_manifest/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md index fb4372dcb81f220..c86c8c910c36ca0 100644 --- a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -5,7 +5,7 @@ page-type: how-to sidebar: pwasidebar --- -[Progressive Web App (PWA)](/en-US/docs/Web/Progressive_web_apps) manifests can be localized using a combination of the [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) manifest member suffix, the [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) member, and the [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) member. +[Progressive Web App (PWA)](/en-US/docs/Web/Progressive_web_apps) manifests can be localized using a combination of localizable members, which have the suffix [`_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized), and the [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) and [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) members. Manifest localization allows the browser to choose between different text strings (for app names and descriptions, for example) and icons when loading the app to best suit the user's language preferences. From ff1e3571dc6188e945ce0e65de690ea1d743b54a Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 3 Jul 2026 09:13:32 +0100 Subject: [PATCH 06/12] Update files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md Co-authored-by: Hamish Willee --- .../how_to/localize_an_app_manifest/index.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md index c86c8c910c36ca0..dc4caa1bee3586f 100644 --- a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -9,7 +9,11 @@ sidebar: pwasidebar Manifest localization allows the browser to choose between different text strings (for app names and descriptions, for example) and icons when loading the app to best suit the user's language preferences. -This guide shows how to localize a PWA manifest, using the following example as a starting point: +This guide shows how to localize a PWA manifest. + +## Example non-localised PWA + +The rest of this guide develops a multilingual PWA manifest using the following example as a starting point. ```json { From ca38a9f276240ed32e1a489c469cd8c8005c4376 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 3 Jul 2026 09:14:07 +0100 Subject: [PATCH 07/12] Update files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md Co-authored-by: Hamish Willee --- .../how_to/localize_an_app_manifest/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md index dc4caa1bee3586f..df2afd2d8f487eb 100644 --- a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -86,7 +86,7 @@ Let's see what this could look like for our example: } ``` -In this case, we've used the string form for all the languages, except for Urdu, which uses the object form. This is because Urdu is an RTL language — we have specified a `dir` value of `rtl` for it, so that browsers will display it correctly. +In this case, we've used the string form for all the languages, except for Urdu, which uses the object form. We've done it this way because Urdu is an RTL language, and we need to specify a `dir` value of `rtl` for it so that browsers will display it correctly. ## Localizing the other text-based members From ae6c7b60837c41cb910b2f1444c4bf092bce388d Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 3 Jul 2026 09:15:29 +0100 Subject: [PATCH 08/12] Update files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md Co-authored-by: Hamish Willee --- .../how_to/localize_an_app_manifest/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md index df2afd2d8f487eb..e4fbd9c4d7db2d3 100644 --- a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -114,7 +114,7 @@ The French (`fr`) `short_name` translation shows typical usage of the object val ## Localizing the `icon` member -The `icon` localization is covered in a separate section because localized images are handled somewhat differently to localized text. The properties of each `*_localized` member (`icon_localized`, in this case) are equal to an array of objects containing the same properties as the non-localized original (`icon`); each one provides details for a localized image. +Localized images are handled somewhat differently to localized text. The properties of each `*_localized` member (`icon_localized`, in this case) are equal to an array of objects containing the same properties as the non-localized original (`icon`); each one provides details for a localized image. Let's see what this looks like: From 0e0d37dcb1c0fc4334785ab3a7017b187f583ca9 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Thu, 9 Jul 2026 16:37:33 +0100 Subject: [PATCH 09/12] Correct role of lang and dir members in localization --- .../how_to/localize_an_app_manifest/index.md | 28 ++----- .../reference/_star__localized/index.md | 75 ++++++++++++------- .../manifest/reference/dir/index.md | 19 ++--- .../manifest/reference/lang/index.md | 19 ++--- 4 files changed, 69 insertions(+), 72 deletions(-) diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md index e4fbd9c4d7db2d3..1b62a027949e0a7 100644 --- a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -5,15 +5,16 @@ page-type: how-to sidebar: pwasidebar --- -[Progressive Web App (PWA)](/en-US/docs/Web/Progressive_web_apps) manifests can be localized using a combination of localizable members, which have the suffix [`_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized), and the [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) and [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) members. - -Manifest localization allows the browser to choose between different text strings (for app names and descriptions, for example) and icons when loading the app to best suit the user's language preferences. +[Progressive Web App (PWA)](/en-US/docs/Web/Progressive_web_apps) manifest localization allows the browser to choose between different text strings (for app names and descriptions, for example) and icons when loading the app to best suit the user's language preferences. Manifests can be localized using localizable members, which have the suffix [`_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized). This guide shows how to localize a PWA manifest. +> [!NOTE] +> The [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) and [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) manifest members have no effect on manifest localization. The language is chosen based on the user's browser language settings. + ## Example non-localised PWA -The rest of this guide develops a multilingual PWA manifest using the following example as a starting point. +This guide develops a multilingual PWA manifest using the following example as a starting point. ```json { @@ -39,17 +40,6 @@ The rest of this guide develops a multilingual PWA manifest using the following } ``` -## Set a default language and direction - -The [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) and [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) members define a default language and language direction for the app. These will be assumed by the browser if no language and direction more suitable for the user's preferences are found in the [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) variants. In such cases, the non-prefixed members are used (for example, `name`). - -Set a suitable default language and direction like so: - -```json -"lang": "en-US", -"dir": "ltr" -``` - ## Choose the manifest members you want to localize The following members support localized variants: @@ -88,6 +78,8 @@ Let's see what this could look like for our example: In this case, we've used the string form for all the languages, except for Urdu, which uses the object form. We've done it this way because Urdu is an RTL language, and we need to specify a `dir` value of `rtl` for it so that browsers will display it correctly. +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. + ## Localizing the other text-based members We can follow the same pattern as we did for the `name` member to localize the `short_name` and `description` members: @@ -110,7 +102,7 @@ We can follow the same pattern as we did for the `name` member to localize the ` }, ``` -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 with a `lang` property specified. 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). ## Localizing the `icon` member @@ -196,8 +188,6 @@ Putting this all together, the complete manifest looks like this: "type": "image/png" } ], - "lang": "en-US", - "dir": "ltr", "name_localized": { "fr": "L'application de saucisse SuperSausage", "de": "Die SuperWurst-App", @@ -277,7 +267,5 @@ Putting this all together, the complete manifest looks like this: ## See also -- [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) manifest member -- [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) manifest member - [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) manifest members - [Localization support for web app manifests](https://developer.chrome.com/blog/manifest-localization) on developer.chrome.com (2026) diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md index c10b623ea675dbf..38b7ba21eff7141 100644 --- a/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md +++ b/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md @@ -6,7 +6,7 @@ browser-compat: manifests.webapp.localizable_members sidebar: pwasidebar --- -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 language preferences. +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 @@ -35,18 +35,18 @@ The `_localized` suffix is added to manifest members to create localized variant - `text_l10n` - : An object or a string containing a text localization; see [text localization](#text_localization). - `image_l10n` - - : An array of objects containing references to localized image resources; see [image localization](#image_localization). + - : An array of objects containing references to localized image resources; see [icon localization](#icon_localization). #### Text localization -When the localized variant is providing a localization of a text value, the property values can be objects or strings. +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_inline}} - - : A string representing the text direction of the localized text, used in cases where the required direction of a localized string differs from the default direction set in the manifest (see [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir)). Valid values of `dir` are: + - : 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 browser will use heuristics to estimate the display direction of the text. - `ltr` @@ -58,20 +58,22 @@ The object representation can have the following properties: In cases where the `dir` and `lang` properties do not need to be specified, the shorthand string representation can be used. This consists of a string containing the localized text `value`. -#### Image localization +#### Icon localization -When the localized variant is providing a localization of an image resource, the property values are arrays containing one or more objects representing image choices. +When the localized variant provides localized icon details, the property values are arrays containing one or more objects representing icon choices. -The exact properties contained within each object will be the same as the properties contained within the objects included with the non-localized versions of the members: +The exact properties contained within each object will be the same as the properties contained within the non-localized versions of the members: - For `icons_localized`, the objects can have the same properties as the [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) member: `src`, `sizes`, `type`, and `purpose`. - For `shortcuts_localized`, the objects can have the same properties as the [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts) member: `name`, `short_name`, `description`, `url`, and [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons). ## Description -The `_localized` suffix, along with the [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) and [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) members, are used to create localized manifests. +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 language preferences. 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. +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. Members for which localized variants are supported: @@ -85,28 +87,53 @@ Members for which localized variants are supported: Localized text field properties have values equal to objects or strings. -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. - -The French variant is specified as French Canadian (`fr-CA`) in its `lang` property, with a direction (`dir`) of `ltr`, while the Arabic variant has its `dir` specified as `rtl`. The German variant doesn't need its `lang` or `dir` specified, so its value is a string containing the localized text. +For example: ```json { - "lang": "en-US", - "dir": "ltr", - "name": "Color Picker", + ... + "name": "The SuperSausage sausage app", "name_localized": { - "de": "Farbwähler", - "fr": { "value": "Sélecteur de Couleur", "lang": "fr-CA", "dir": "ltr" }, - "ar": { "value": "`منتقي` `الألوان`", "dir": "rtl" } + "fr": "L'application de saucisse SuperSausage", + "de": "Die SuperWurst-App", + "ur": { + "dir": "rtl", + "value": "سپر ساسیج ساسیج ایپ" + }, + "ja": "スーパーソーセージのソーセージアプリ" } + ... } ``` -The `lang` and `dir` members define a default language and language direction that will be assumed by the browser if no language more suitable for the user's preferences is found in the `name_localized` variants. In such cases, the `name` member is used. +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. -### Localized images +The `fr`, `de`, and `ja` members have string values representing the localized text for that language. The `ur` member needs to specify an RTL directionality, so its value is an object containing both the localized text (in the `value` property) and the directionality (in the `dir` property). -A localized icon set will look like this: +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": "SuperSausage" + }, + "de": "SuperWurst", + "ur": "سپر ساسیج", + "ja": "スーパーソーセージ" + }, + ... +} +``` + +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). This is done by specifying a `lang` value of `en-US` inside the variant. + +### Localized icons + +A localized icon set consists of an object containing multiple arrays, each one containing objects representing the icon choices for a different locale: ```json { @@ -143,9 +170,7 @@ A localized icon set will look like this: } ``` -If the user has specified a preference for German, Arabic, or French, an entry from the appropriate `icons_localized` member will be used. - -The `icons` member specifies the default icon that will be used if no language more suitable for the user's language preferences than the default `lang` is found in the `icons_localized` variants. +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. ## Examples @@ -164,7 +189,5 @@ For complete demos, check out; ## See also -- [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) manifest member -- [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) manifest member - [Localize an app manifest](/en-US/docs/Web/Progressive_web_apps/How_to/Localize_an_app_manifest) - [Localization support for web app manifests](https://developer.chrome.com/blog/manifest-localization) on developer.chrome.com (2026) diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md index 2aea7f7df484c22..cd9680d6ba42825 100644 --- a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md +++ b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md @@ -6,8 +6,10 @@ browser-compat: manifests.webapp.dir sidebar: pwasidebar --- -The `dir` manifest member is used to specify a default language directionality for your web application, which will be used unless overriden by a different `dir` value found in a [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) member. -If not specifies, the default direction is inferred from the default language, as specfiied using [`lang`]. +The `dir` manifest member is used to specify a language directionality for your web application. + +> [!NOTE] +> The `dir` manifest member has no effect on manifest localization implemented via [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) members. In such cases, the language is chosen based on the user's browser language settings. ## Syntax @@ -32,25 +34,16 @@ A string representing the app's text direction. Valid values of `dir` are: ### Basic usage -in this example, the app's default `lang` is `en-US`, and its default `dir` is `ltr`. Its default `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. - -The French variant is specified as French Canadian (`fr-CA`) in its `lang` property, with a direction (`dir`) of `ltr`, while the Arabic variant has its `dir` specified as `rtl`. The German variant doesn't need its `lang` or `dir` specified, so its value is a string containing the localized text. +In this example, the app's `lang` is set as `en-US`, and its default `dir` is `ltr`. ```json { "lang": "en-US", "dir": "ltr", - "name": "Color Picker", - "name_localized": { - "de": "Farbwähler", - "fr": { "value": "Sélecteur de Couleur", "lang": "fr-CA", "dir": "ltr" }, - "ar": { "value": "`منتقي` `الألوان`", "dir": "rtl" } - } + ... } ``` -The `lang` and `dir` members define a default language and language direction that will be assumed by the browser if no language more suitable for the user's preferences is found in the `name_localized` variants. In such cases, the `name` member is used. - ## Specifications {{Specifications}} diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md index 8ba6a36fa9f0624..3d4fc360f8f83e6 100644 --- a/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md +++ b/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md @@ -6,7 +6,10 @@ browser-compat: manifests.webapp.lang sidebar: pwasidebar --- -The `lang` manifest member is used to specify a default language for your web application, which will be used unless overriden by a different `lang` value found in a [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) member. +The `lang` manifest member is used to specify a language for your web application. + +> [!NOTE] +> The `lang` manifest member has no effect on manifest localization implemented via [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) members. In such cases, the language is chosen based on the user's browser language settings. ## Syntax @@ -24,26 +27,16 @@ a {{glossary("BCP 47 language tag")}} representing the app's default language. ### Basic usage -In this example, the app's default `lang` is `en-US` and default `dir` is `ltr`. -The default `name` is "Color picker", but we have also defined 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 their selected language. - -The French variant is specified as French Canadian (`fr-CA`) in its `lang` property, with a direction (`dir`) of `ltr`, while the Arabic variant has its `dir` specified as `rtl`. The German variant doesn't need its `lang` or `dir` specified, so its value is a string containing the localized text. +In this example, the app's `lang` is set as `en-US`, and its default `dir` is `ltr`. ```json { "lang": "en-US", "dir": "ltr", - "name": "Color Picker", - "name_localized": { - "de": "Farbwähler", - "fr": { "value": "Sélecteur de Couleur", "lang": "fr-CA", "dir": "ltr" }, - "ar": { "value": "`منتقي` `الألوان`", "dir": "rtl" } - } + ... } ``` -The `lang` and `dir` members define a default language and language direction that will be assumed by the browser if no language more suitable for the user's preferences is found in the `name_localized` variants. In such cases, the `name` member is used. - ## Specifications {{Specifications}} From 2f6abb83220c8abee0f8c853b207a8c6b3db576b Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Thu, 9 Jul 2026 17:19:42 +0100 Subject: [PATCH 10/12] Typo fixes --- .../how_to/localize_an_app_manifest/index.md | 2 +- .../manifest/reference/_star__localized/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md index 1b62a027949e0a7..52e1c6474e691df 100644 --- a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -102,7 +102,7 @@ We can follow the same pattern as we did for the `name` member to localize the ` }, ``` -The French (`fr`) `short_name` translation shows typical usage of the object value form with a `lang` property specified. 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 with a `lang` property specified. 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). ## Localizing the `icon` member diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md index 38b7ba21eff7141..e44a9a4a4ca2410 100644 --- a/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md +++ b/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md @@ -129,7 +129,7 @@ Sometimes you will want to specify a different `lang` value inside a localized v } ``` -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). This is done by specifying a `lang` value of `en-US` inside the variant. +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). This is done by specifying a `lang` value of `en-US` inside the variant. ### Localized icons From 38f91d4fcfc3e3d5ac13d747614c998d2ee000ef Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 10 Jul 2026 12:02:44 +0100 Subject: [PATCH 11/12] Remove dir and lang member pages, as they are not supported --- .../how_to/localize_an_app_manifest/index.md | 5 +- .../manifest/reference/dir/index.md | 58 ------------------- .../manifest/reference/lang/index.md | 51 ---------------- 3 files changed, 1 insertion(+), 113 deletions(-) delete mode 100644 files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md delete mode 100644 files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md index 52e1c6474e691df..bbf147037b6f871 100644 --- a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -5,13 +5,10 @@ page-type: how-to sidebar: pwasidebar --- -[Progressive Web App (PWA)](/en-US/docs/Web/Progressive_web_apps) manifest localization allows the browser to choose between different text strings (for app names and descriptions, for example) and icons when loading the app to best suit the user's language preferences. Manifests can be localized using localizable members, which have the suffix [`_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized). +[Progressive Web App (PWA)](/en-US/docs/Web/Progressive_web_apps) manifest localization allows the browser to choose between different text strings and icons when loading an app to best suit the user's localization preferences, based on their browser language settings. Manifests can be localized using localizable members, which have the suffix [`_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized). This guide shows how to localize a PWA manifest. -> [!NOTE] -> The [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) and [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) manifest members have no effect on manifest localization. The language is chosen based on the user's browser language settings. - ## Example non-localised PWA This guide develops a multilingual PWA manifest using the following example as a starting point. diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md deleted file mode 100644 index cd9680d6ba42825..000000000000000 --- a/files/en-us/web/progressive_web_apps/manifest/reference/dir/index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: dir -slug: Web/Progressive_web_apps/Manifest/Reference/dir -page-type: web-manifest-member -browser-compat: manifests.webapp.dir -sidebar: pwasidebar ---- - -The `dir` manifest member is used to specify a language directionality for your web application. - -> [!NOTE] -> The `dir` manifest member has no effect on manifest localization implemented via [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) members. In such cases, the language is chosen based on the user's browser language settings. - -## Syntax - -```json-nolint -"dir": "auto" -"dir": "ltr" -"dir": "rtl" -``` - -### Values - -A string representing the app's text direction. Valid values of `dir` are: - -- `auto` - - : The default. Specifies that the text direction is unknown. The browser will use heuristics to infer the display direction of the text. -- `ltr` - - : Specifies a left-to-right text direction. -- `rtl` - - : Specifies a right-to-left text direction. - -## Examples - -### Basic usage - -In this example, the app's `lang` is set as `en-US`, and its default `dir` is `ltr`. - -```json -{ - "lang": "en-US", - "dir": "ltr", - ... -} -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`lang`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/lang) manifest member -- [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) manifest members diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md deleted file mode 100644 index 3d4fc360f8f83e6..000000000000000 --- a/files/en-us/web/progressive_web_apps/manifest/reference/lang/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: lang -slug: Web/Progressive_web_apps/Manifest/Reference/lang -page-type: web-manifest-member -browser-compat: manifests.webapp.lang -sidebar: pwasidebar ---- - -The `lang` manifest member is used to specify a language for your web application. - -> [!NOTE] -> The `lang` manifest member has no effect on manifest localization implemented via [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) members. In such cases, the language is chosen based on the user's browser language settings. - -## Syntax - -```json-nolint -"lang": "en-US" -"lang": "ja" -"lang": "uk" -``` - -### Values - -a {{glossary("BCP 47 language tag")}} representing the app's default language. - -## Examples - -### Basic usage - -In this example, the app's `lang` is set as `en-US`, and its default `dir` is `ltr`. - -```json -{ - "lang": "en-US", - "dir": "ltr", - ... -} -``` - -## Specifications - -{{Specifications}} - -## Browser compatibility - -{{Compat}} - -## See also - -- [`dir`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/dir) manifest member -- [`*_localized`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/*_localized) manifest members From 96f80a13d655749a04fce4efd2d21085dd611976 Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Fri, 10 Jul 2026 13:17:37 +0100 Subject: [PATCH 12/12] Add details of localizing shortcuts member --- .../how_to/localize_an_app_manifest/index.md | 144 +++++++++++++++++- .../reference/_star__localized/index.md | 80 +++++++--- 2 files changed, 203 insertions(+), 21 deletions(-) diff --git a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md index bbf147037b6f871..7e18e177d69da6a 100644 --- a/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/localize_an_app_manifest/index.md @@ -33,6 +33,22 @@ This guide develops a multilingual PWA manifest using the following example as a "sizes": "256x256", "type": "image/png" } + ], + "shortcuts": [ + { + "name": "Open menu", + "short_name": "Menu", + "description": "Go to the menu.", + "url": "./menu", + "icons": [ + { + "src": "./icons/menu-128.png", + "sizes": "128x128", + "type": "image/png", + "purpose": "any" + } + ] + } ] } ``` @@ -47,7 +63,7 @@ The following members support localized variants: - [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) - [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts) -Our sample manifest has all of these except for `shortcuts`; we'll show how to localize each one. +Our sample manifest has all of these; we'll show how to localize each one. ## Choose the languages you want to support @@ -101,9 +117,9 @@ We can follow the same pattern as we did for the `name` member to localize the ` The French (`fr`) `short_name` translation shows typical usage of the object value form with a `lang` property specified. 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). -## Localizing the `icon` member +## Localizing the `icons` member -Localized images are handled somewhat differently to localized text. The properties of each `*_localized` member (`icon_localized`, in this case) are equal to an array of objects containing the same properties as the non-localized original (`icon`); each one provides details for a localized image. +Localized icons are handled somewhat differently to localized text. The properties of each `icons_localized` member are equal to an array of objects containing the same properties as the non-localized `icons` member; each one provides details for a localized icon. Let's see what this looks like: @@ -160,6 +176,58 @@ Let's see what this looks like: } ``` +## Localizing the `shortcuts` member + +In the case of the `shortcuts` member, you don't specify the localizations inside a `shortcuts_localized` member. Instead, you provide `*_localized` versions of the `name`, `short_name`, `description`, and `icons` members nested inside the `shortcut` member. + +For our example, this looks like so: + +```json +"shortcuts": [ + { + "name": "Open menu", + "name_localized": { + "fr": "Menu ouvert", + "de": "Menü öffnen", + "ur": { "value": "اوپن مینو", "dir": "rtl" }, + "ja": "メニューを開く" + }, + "short_name": "Menu", + "short_name_localized": { + "fr": "Menu", + "de": "Speisekarte", + "ur": { "value": "مینو", "dir": "rtl" }, + "ja": "メニュー" + }, + "description": "Go to the menu.", + "description_localized": { + "fr": "Allez au menu.", + "de": "Geh zur Speisekarte.", + "ur": { "value": "مینو پر جائیں۔", "dir": "rtl" }, + "ja": "メニューに行け。" + }, + "url": "./menu", + "icons": [ + { "src": "./icons/menu-128.png", "sizes": "128x128", "type": "image/png", "purpose": "any" } + ], + "icons_localized": { + "fr": [ + { "src": "./icons/l10n/fr/menu-128.png", "sizes": "128x128", "type": "image/png", "purpose": "any" } + ], + "de": [ + { "src": "./icons/l10n/de/menu-128.png", "sizes": "128x128", "type": "image/png", "purpose": "any" } + ], + "ur": [ + { "src": "./icons/l10n/ur/menu-128.png", "sizes": "128x128", "type": "image/png", "purpose": "any" } + ], + "ja": [ + { "src": "./icons/l10n/ja/menu-128.png", "sizes": "128x128", "type": "image/png", "purpose": "any" } + ] + } + } +] +``` + ## Finished manifest Putting this all together, the complete manifest looks like this: @@ -258,7 +326,75 @@ Putting this all together, the complete manifest looks like this: "type": "image/png" } ] - } + }, + "shortcuts": [ + { + "name": "Open menu", + "name_localized": { + "fr": "Menu ouvert", + "de": "Menü öffnen", + "ur": { "value": "اوپن مینو", "dir": "rtl" }, + "ja": "メニューを開く" + }, + "short_name": "Menu", + "short_name_localized": { + "fr": "Menu", + "de": "Speisekarte", + "ur": { "value": "مینو", "dir": "rtl" }, + "ja": "メニュー" + }, + "description": "Go to the menu.", + "description_localized": { + "fr": "Allez au menu.", + "de": "Geh zur Speisekarte.", + "ur": { "value": "مینو پر جائیں۔", "dir": "rtl" }, + "ja": "メニューに行け。" + }, + "url": "./menu", + "icons": [ + { + "src": "./icons/menu-128.png", + "sizes": "128x128", + "type": "image/png", + "purpose": "any" + } + ], + "icons_localized": { + "fr": [ + { + "src": "./icons/l10n/fr/menu-128.png", + "sizes": "128x128", + "type": "image/png", + "purpose": "any" + } + ], + "de": [ + { + "src": "./icons/l10n/de/menu-128.png", + "sizes": "128x128", + "type": "image/png", + "purpose": "any" + } + ], + "ur": [ + { + "src": "./icons/l10n/ur/menu-128.png", + "sizes": "128x128", + "type": "image/png", + "purpose": "any" + } + ], + "ja": [ + { + "src": "./icons/l10n/ja/menu-128.png", + "sizes": "128x128", + "type": "image/png", + "purpose": "any" + } + ] + } + } + ] } ``` diff --git a/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md b/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md index e44a9a4a4ca2410..e9900cfcf02aa88 100644 --- a/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md +++ b/files/en-us/web/progressive_web_apps/manifest/reference/_star__localized/index.md @@ -2,7 +2,7 @@ title: "*_localized" slug: Web/Progressive_web_apps/Manifest/Reference/*_localized page-type: web-manifest-member -browser-compat: manifests.webapp.localizable_members +browser-compat: manifests.webapp.localized_members sidebar: pwasidebar --- @@ -11,18 +11,18 @@ The `_localized` suffix is added to manifest members to create localized variant ## Syntax ```json-nolint -/* Localized text value */ +/* Localized text values */ "member_localized": { "lang1": text_l10n, "lang2": text_l10n, "langN": text_l10n, } -/* Localized image resource */ +/* Localized icon resources */ "member_localized": { - "lang1": image_l10n, - "lang2": image_l10n, - "langN": image_l10n, + "lang1": icon_l10n, + "lang2": icon_l10n, + "langN": icon_l10n, } ``` @@ -34,8 +34,8 @@ The `_localized` suffix is added to manifest members to create localized variant - : Each object contains one or more properties with keys equal to a {{glossary("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](#text_localization). - - `image_l10n` - - : An array of objects containing references to localized image resources; see [icon localization](#icon_localization). + - `icon_l10n` + - : An array of objects containing references to localized icon resources; see [icon localization](#icon_localization). #### Text localization @@ -56,16 +56,17 @@ The object representation can have the following properties: - `lang` {{optional_inline}} - : A string containing a BCP 47 language tag, used in cases where localized text needs to be presented in a different language from the user's locale. -In cases where the `dir` and `lang` properties do not need to be specified, the shorthand string representation can be used. This consists of a string containing the localized text `value`. +In cases where the `dir` and `lang` properties do not need to be specified, a shorthand string representation can be used, which contains the localized text `value`. #### Icon localization -When the localized variant provides localized icon details, the property values are arrays containing one or more objects representing icon choices. +The `icons_localized` member object property values are arrays containing one or more objects representing localized icon choices. -The exact properties contained within each object will be the same as the properties contained within the non-localized versions of the members: +Each object contains the same properties as the non-localized [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) member: `src`, `sizes`, `type`, and `purpose`. -- For `icons_localized`, the objects can have the same properties as the [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) member: `src`, `sizes`, `type`, and `purpose`. -- For `shortcuts_localized`, the objects can have the same properties as the [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts) member: `name`, `short_name`, `description`, `url`, and [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons). +#### Shortcut localization + +The [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/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`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) members nested inside the `shortcut` member. ## Description @@ -75,13 +76,12 @@ You can add the `_localized` suffix to a supporting manifest member to create lo 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. -Members for which localized variants are supported: +Members for which localized variants are supported (both at the manifest top level, and inside the [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts) member): - [`name`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/name) - [`short_name`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/short_name) - [`description`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/description) - [`icons`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons) -- [`shortcuts`](/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts) ### Localized text @@ -133,7 +133,7 @@ In this case, our French audience knows our app by its English brand name — "S ### Localized icons -A localized icon set consists of an object containing multiple arrays, each one containing objects representing the icon choices for a different locale: +A localized `icons` set consists of an object containing multiple arrays, each one containing objects representing the icon choices for a different locale: ```json { @@ -172,9 +172,55 @@ A localized icon set consists of an object containing multiple arrays, each one 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. +### Localized shortcuts + +Localized shortcut sub-members are provided inside the `shortcuts` member. + +For example: + +```json +"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" } + ] + } + } +], +``` + ## Examples -For complete demos, check out; +For examples, check out; - The [PWA manifest localization demo](https://microsoftedge.github.io/Demos/pwa-manifest-localization/) app ([see source code](https://github.com/MicrosoftEdge/Demos/tree/main/pwa-manifest-localization/)). - Our [Localize an app manifest](/en-US/docs/Web/Progressive_web_apps/How_to/Localize_an_app_manifest) How to guide.