Manifest 中的清单成员
lang、dir 与 *_localized 清单成员
发布于
清单的 lang 和 dir 成员分别声明文本所用的语言和书写方向。要提供多种语言版本,可以用
*_localized 成员(name_localized、short_name_localized、description_localized、
icons_localized),按 BCP 47 语言标签填写,普通成员保留为回退值。本地化按字段设置,
没有一个统一的 translations 成员。
Chrome 148 与 Edge 148 读取 name、short_name、description、icons 的 *_localized
成员,以及每个 shortcuts 条目内同样的四个字段(developer.chrome.com 的清单本地化公告)。
MDN 记录顶层的 dir 与 lang 没有任何浏览器实现;Chromium 读取的是本地化值内部的 lang 与
dir 覆盖。Firefox 157 与 Safari 27 丢弃所有 *_localized 成员,只显示普通的 name。
| 成员 | 类型与取值 | 默认值与无效值 |
|---|---|---|
lang |
BCP 47 语言标签字符串,例如 en-AU 或 zh-Hans-CN,比较时不区分大小写 |
未设置时语言未知。浏览器丢弃格式错误的标签。 |
dir |
字符串,可选 ltr、rtl 或 auto |
默认 auto,由浏览器根据文本估计方向。无法识别的值也按 auto 处理。 |
*_localized |
以语言标签为键的对象。文本值可以是字符串,也可以是 { "value": "...", "lang": "...", "dir": "..." } 形式的对象。icons_localized 的每个值都是完整图标数组,结构与 icons 相同。 |
省略时,所有语言都使用普通成员。 |
示例值为 "name_localized": { "de": "Farbwähler", "en-GB": { "value": "Colour Picker" } }。
浏览器按自己的语言列表选取最匹配的条目,找不到就回退到普通成员。具体怎样匹配语言标签,由浏览器决定,规范没有限定算法。本地化图标数组会整体替换该语言下的 icons,而不是与之合并,所以每个语言条目都要带上
完整的尺寸集合。shortcuts 没有 shortcuts_localized;四个 *_localized 成员嵌套在每个快捷
方式对象内部。
文本类 *_localized 成员不是对象时,解析器不给任何消息直接丢弃它,普通成员照常生效。不是对象的 icons_localized 会被丢弃,并记录 property 'icons_localized' ignored, type object expected.。
某种语言没有对应条目时,就用普通的 name 和 description 回退。
本地化名称与描述,并以普通成员回退
链接到“本地化名称与描述,并以普通成员回退”一节lang 和 dir 描述这些普通值。
以德语为主的应用可以把 lang 设为 de,再把英文填在 name_localized.en 下。
{ "lang": "de", "dir": "ltr", "name": "Farbwähler", "description": "Farben aus Bildern auswählen und als Palette speichern.", "name_localized": { "en": "Color Picker", "en-GB": "Colour Picker", "fr": "Sélecteur de couleur" }, "description_localized": { "en": "Pick colors from images and save them as a palette." }}浏览器语言为 en-US 时,会选中 en 条目的 Color Picker;设为 en-GB 则使用英式拼法。
西班牙语没有对应条目,会回退到普通成员中的德语,此时可以补上 es 条目。
在从右到左的区域设置里保留英文品牌名
链接到“在从右到左的区域设置里保留英文品牌名”一节当值的语言或方向与键所暗示的不同时,用值对象携带自己的 lang 与 dir。这里阿拉伯语条目保留
拉丁字母的品牌名,并在一份从右到左的清单里把它标记为从左到右的英文。
{ "lang": "ar", "dir": "rtl", "name": "منتقي الألوان", "short_name_localized": { "ar": { "value": "ColorPick", "lang": "en", "dir": "ltr" }, "en": "ColorPick" }}如果没有为值单独指定 dir,启动器在阿拉伯文旁显示拉丁字母标签时,双向文本渲染器可能排错位置。
规范允许在值中覆盖方向,以解决这个问题。
提供本地化图标并检查浏览器解析出的结果
链接到“提供本地化图标并检查浏览器解析出的结果”一节含有文字的图标需要按语言给出数组。随后脚本读取清单,报告浏览器会为自己的语言选择哪个条目,
没有匹配时回退到普通的 icons,这也正是不支持 *_localized 的浏览器的做法。
{ "icons": [{ "src": "/icons/en-512.png", "sizes": "512x512", "type": "image/png" }], "icons_localized": { "ja": [{ "src": "/icons/ja-512.png", "sizes": "512x512", "type": "image/png" }] }}async function resolvedIcons() { const link = document.querySelector('link[rel="manifest"]'); if (!link) return []; const manifest = await fetch(link.href).then((r) => r.json()); const localized = manifest.icons_localized ?? {}; const tag = navigator.languages.find((l) => localized[l] || localized[l.split('-')[0]]); if (!tag) return manifest.icons ?? []; // 无匹配或不支持:普通图标 return localized[tag] ?? localized[tag.split('-')[0]];}这个函数实现了回退规则,但没有复现浏览器的精确匹配算法。结果可用于设置页预览,无法保证操作系统 最终显示的就是这个图标。
另请参阅
链接到“另请参阅”一节- 清单本地化浏览器支持
- name 与 short_name 清单成员
- description 清单成员
- icons 清单成员
- shortcuts 清单成员
- Web Application Manifest: lang member(w3.org)
- Localization support for web app manifests(developer.chrome.com)
- *_localized(developer.mozilla.org)
规范
| 规范 | 状态 |
|---|---|
| Web Application Manifest: lang member | W3C |
| Web Application Manifest: dir member | W3C |