# 多语言适配

- 开发者工具版本要求：≥ 1.06.2312122（建议使用最新的 nightly 开发者工具）。
- 当前可支持 App 名称、隐私信息访问许可描述、隐私弹窗内容以及启动页的多语言适配。

## 一、使用步骤

### 1.1 下载工具并创建文件夹

- 下载最新 [nightly 开发者工具](/miniprogram/dev/devtools/log.md)。
- 如果是存量多端项目，在项目目录中新建文件夹用于放置不同语言的配置文件（建议建在项目根目录，可随其他代码一起 push 到 git 仓库）。
- 如果是全新刚升级的多端项目，则开发者工具默认已经为开发者创建 `i18n` 文件夹，并且生成了 base.json 以及默认将 Name 以及适配文件的文件夹填充。

    ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202312121713361.png)

### 1.2 创建基准配置文件

- 如果是存量多端项目，需手动在步骤 1 的文件夹里创建 base.json（这个是基准文件，会被用在没有设置国际化的其他语言、国家、地区上）。

### 1.3 创建其他语言配置文件

- json 文件的命名规范是：BCP 47（需要注意 iOS 中因为系统原因无法使用 zh 需要使用 zh-Hans 或 zh-Hant）
- 创建其他语言的 json 文件，常见语言对应的 json 文件名：

    | 语言     | json 文件名 |
    |  :----: |  :----:   |
    | 简体中文     | zh.json（iOS 为 zh-Hans.json 或 zh-Hant.json） |
    | 繁体中文（香港） | zh-Hk.json   |
    | 繁体中文（台湾） | zh-TW.json   |
    | 英文     | en.json   |
    | 法语     | fr.json   |
    | 德语     | de.json   |
    | 俄语     | ru.json   |
    | 西班牙语  | es.json   |
    | 日语     | ja.json   |
    | 韩语     | ko.json   |
    | 阿拉伯语  | ar.json   |

- 并在 json 中按照以下格式编写国际化文本（以配置 App 名称为例子）。

    ```json
    {
        "ios": {
            "name": "xx" 
        },
        "android": {
            "name": "yy"
        },
        "common": {
            "someDesc": "zz"
        }
    }
    ```

注意：其中相同字段国际化读取时的覆盖关系优先级为：zh-Hk.json > zh-Hans.json > zh.json > base.json

### 1.4 project.miniapp.json 完成多语言适配

- 配置多语言适配的文件夹路径。

    ![](https://res.wx.qq.com/op_res/-0ZE97KOGsTezE1AEQO6-DEE9duT678ur--Lpi5WRcNGZsYTab8QKsS892HjNdvQb7z5ZVQFju3vd9X4gNqqsg)

- 前往 project.miniapp.json，在需要进行多语言适配的字段（如：名字、隐私信息访问许可描述）以 %i18n_key% 的形式填入，例如：%name%、%someDesc%

  ![](https://res.wx.qq.com/op_res/-0ZE97KOGsTezE1AEQO6-ANmduaQ4x5nQt8lBwEasC0fA0A_ZLQ0ND_k3vezGVxNPKFJI32Rqug2W2mlf2JWwQ)

### 1.5 隐私提示框多语言适配示例

- 可在 `i18n` 文件夹中继续创建 `privacy` 文件夹放置不同语言版本的隐私提示窗内容。

    ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202312121725752.png)

- 然后在 `i18n` 文件夹里各语言的 json 文件中配置 privacy 内容，例如

    ``` json
    {
        "ios": {
            "name": "xx" ,
            "privacy":"i18n/privacy/fr.json"
        },
        "android": {
            "name": "yy"
        },
        "common": {
            "someDesc": "zz"
        }
    }
    ```

    ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202312121729361.png)

- 最后，在 project.miniapp.json 中配置 Android 和 iOS 对应的 `privacy template` 的路径。

    ![](https://res.wx.qq.com/op_res/-0ZE97KOGsTezE1AEQO6-DatNfL3tZwZ_TFF0wuYBDs4Mk3MCKp5dJCyUxMUXjyTI8-JD2RDY3A4xaMz-4-D7w)

    ![](https://res.wx.qq.com/op_res/-0ZE97KOGsTezE1AEQO6-Do9CWCrdvBprqoUo1L_iR4i6N2PCGS5PpLLLqjyWLej33-cjkXaB-GSywItqudTFw)

### 1.6 启动页多语言适配示例

注意：开发者工具需 ≥ 1.06.2407092

- 在国际化文件中添加 {splashscreen} 字段，值为启动页图片地址，例如 base.json 中的配置示参考。

    ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F%E6%88%AA%E5%B1%8F2024-07-09%2011.04.16.png)

- 在 project.miniapp.json 文件中，以 %{splashscreen}% 格式使用国际化启动页图片。

    ![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F%E6%88%AA%E5%B1%8F2024-07-09%2011.04.57.png)

#### iOS 注意事项

- 启动页图片有 2 个阶段，阶段 1 的图片会在第一次 APP 启动时根据此时用户的语言设置确定，之后再切换语言也不会改变了。阶段 2 的图片会时刻跟随用户的语言设置进行改变。

### 1.7 权限描述配置多语言适配

Android 的权限描述以及 iOS 的隐私信息访问许可描述均支持多语言适配，使用 %{xxxx}% 进行配置即可（参考上面 %name% 的实现）

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202412191948916.png)

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202412191949694.png)

### 1.8 网络异常页配置多语言适配

- 当用户处于无网络或者未允许将网络授权给 App 时，会进入一个网络无权限或者网络未开启的说明页，如下截图：
- 如需对该页面进行多语言适配，可参考下方的说明进行使用（注意，开发者工具版本需要 > 1.06.2412242）

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202412301523768.png)

- 配置 LOCALES，即，国际化文件增加了保留字 LOCALES，用于声明通用国际化配置文件的路径。

```js

{
  "ios": {
    "name": "xx",
    "LOCALES": "path/to/common/locales/config/file/ios.json"
  },
  "android": {
    "name": "yy",
    "LOCALES": "path/to/common/locales/config/file/android.json"
  },
  "common": {
    "name": "zz",
    "LOCALES": "path/to/common/locales/config/file.json"
  }
}

```

* LOCALES 指向的文件，目前支持网络异常落地页国际化，和 iOS 网络拒绝提示页国际化，需按照下面指定的格式编写。

```js

{
  "networkError": {
    "tips": "检测到网络权限可能未开启",
    "confirm": "前往设置",
    "solution": {
      "describe": "查看解决办法",
      "confirm": "知道了",
      "title": "网络设置参照方法",
      "words": "1.点击前往设置，查看是否允许应用使用蜂窝数据。\n2.检查设备的\"设置\"-\"无线局域网\"设置，查看是否有可接入的无线局域网信号。\n3.检查设备是否启用了蜂窝数据(启用后运营商可能会收取数据通信费用）。\n4.如果你已接入无线局域网络：请检查你所连接的网络是否已接入互联网，或该网络是否已允许你的设备访问互联网。"
    }
  },
  "weakNetworkError": {
    "tips": "当前网络连接不可用，请确保手机正常联网后重试",
    "confirm": "立即重试",
    "retry": "重试中......",
    "solution": {
      "describe": "查看解决办法",
      "confirm": "知道了",
      "title": "您的设备未启用移动网络、 Wi-Fi 网络或网络连接异常",
      "words": "如需要连接到互联网，请参考以下几点：\n检查手机中的无线局域网设置，查看是否有可接入的无线局域网信号。\n检查手机是否已接入移动网络，并且手机没有被停机。\n如果您已接入无线局域网：\n请检查您所连接的无线局域网热点是否已接入互联网，或该热点是否已允许您的设备访问互联网。\n"
    },
    "detailedLog": {
      "describe": "错误详细日志",
      "confirm": "知道了"
    }
  }
}

```