跳转到内容

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]];
}

这个函数实现了回退规则,但没有复现浏览器的精确匹配算法。结果可用于设置页预览,无法保证操作系统 最终显示的就是这个图标。

规范

规范状态
Web Application Manifest: lang memberW3C
Web Application Manifest: dir memberW3C