# 清单本地化：lang、dir 与 *_localized 成员

> Web App Manifest 的 dir 与 lang 成员如何为清单的可本地化成员设置默认文字方向与语言，以及 *_localized 成员模式（name_localized、short_name_localized、description_localized、icons_localized）如何提供带回退的分字段翻译。

**一句话：** 清单规范定义了 `dir` 与 `lang`，用于为清单的可本地化成员设置默认文字方向
与语言；同时定义了 `*_localized` 成员模式（`name_localized`、`short_name_localized`、
`description_localized`、`icons_localized`），为各字段提供带自动回退的按语言翻译。清单
中并不存在一个字面名为 `translations` 的成员——分字段翻译正是由 `*_localized` 模式提供
的。

## `dir`：默认文字方向

`dir` 是一个受限字符串，取值为 `"ltr"`（从左到右）、`"rtl"`（从右到左）或 `"auto"`
（默认——方向未知时由用户代理进行估计）。规范指出它"为清单的……可本地化成员指定默认方
向"。若该成员缺失或取值无效，处理算法会将其设为 `"auto"`。

## `lang`：默认语言

`lang` 是一个语言标签字符串，"为清单的……可本地化成员的值指定语言"。若省略，语言将被
视为未知。其值必须是符合 BCP47 的合法 `Language-Tag`（例如 `fr`、`en-AU`、
`zh-Hans-CN`）；语言标签不区分大小写。

MDN 的清单参考文档指出，就目前的实现而言，**`dir`、`lang` 与 `iarc_rating_id` 均未被
浏览器实现**。

## `*_localized`：分字段翻译

清单的每个可本地化成员都有对应的 `*_localized` 成员——`name_localized`、
`short_name_localized`、`description_localized` 和 `icons_localized`——以 BCP 47 语
言标签为键：

```json
{
  "name": "The SuperSausage sausage app",
  "name_localized": {
    "fr": "L'application de saucisse SuperSausage",
    "de": "Die SuperWurst-App"
  }
}
```

本地化文本值可以是纯字符串，也可以是一个对象，包含必需的 `value` 以及可选的
`dir`/`lang` 覆盖项（当某条翻译的方向或语言与其键所暗示的不同时使用——例如为法语用户
保留英文品牌名）：

```json
{
  "short_name_localized": {
    "fr": { "lang": "en-US", "value": "Sausage Super" },
    "de": "SuperWurst"
  }
}
```

`icons_localized` 将每个语言标签映射到自己独立的图标对象数组（形状与 `icons` 相同：
`src`、`sizes`、`type`、`purpose`）。每个本地化图标数组都是独立的——浏览器不会用基础
`icons` 数组中的条目来补充它。

`shortcuts` 没有顶层的 `shortcuts_localized` 成员；相反，`name_localized`/
`short_name_localized`/`description_localized`/`icons_localized` 是嵌套在每个快捷方
式对象内部的。

## 语言匹配与回退

根据规范，用户代理应当选择与用户偏好语言环境最匹配的本地化值；当没有可用的本地化值
时，回退到未本地化的基础成员（`name`、`short_name`、`description`、`icons`）。规范
并未规定具体的标签匹配算法（例如先匹配最精确标签、再逐级回退到更宽泛标签）。

## 实现状态

MDN 的 `*_localized` 参考文档将该模式标记为**实验性**，并提示读者在生产环境依赖它之
前先查看浏览器兼容性数据。`dir` 与 `lang` 则被明确标注为尚未实现。

## 实践清单

- [ ] 不要仅依赖 `dir`/`lang` 来控制方向/语言——MDN 指出二者均未被实现。
- [ ] 使用 `*_localized` 成员提供分字段翻译；将基础的 `name`/`short_name`/
      `description`/`icons` 保留作为未匹配语言环境的回退。
- [ ] 在你提供的每个 `icons_localized` 语言条目中都提供完整的图标集——浏览器不会从基
      础 `icons` 数组中合并图标。
- [ ] 对于快捷方式，将 `*_localized` 成员嵌套在每个快捷方式对象内部；不存在
      `shortcuts_localized`。
- [ ] 在生产环境依赖 `*_localized` 之前，先查看当前的浏览器兼容性数据，因为 MDN 将其
      标记为实验性。