# I18n for Cocos Creator

> 本仓库已暂停维护，仅供存档，建议开发者们在项目层面自行实现多语言切换。

Cocos Creator 3.2 以上版本编辑器扩展：实现 Label 和 Sprite 组件的多语言国际化（i18n）。

注意，多语言国际化和本地化的区别是，国际化需要软件里包括多种语言的文本和图片数据，并根据用户所用设备的默认语言或菜单选择来进行实时切换。而本地化是在发布软件时针对某一特定语言的版本定制文本和图片内容。

本插件是多语言支持插件，因此不包括构建项目时去除一部分多语言数据的功能。

## 插件安装方法

请参考 [扩展编辑器:安装与分享](http://www.cocos.com/docs/creator/extension/install-and-share.html) 文档。

## 语言配置

首先从主菜单打开 i18n 面板： `扩展` -> `I18n Settings`。

然后在弹出的面板里创建包含多语言翻译数据的文件（为了方便使用采用脚本格式存储）：

- 在面板里点击 `+` 按钮，然后在输入框里输入新增语言的 ID，如 `zh`（代表中文），`en`（代表英文）等，最后按下回车确认。
- 新增语言后，会在下方列表里增加一种语言，并且会在项目的 `resources/i18n` 目录下创建对应语言的翻译数据模板，如 `resources/i18n/zh.ts`
- 在 `zh.ts` 里按照格式填入翻译的数据
- 接下来点击列表里每个语言前面的小眼睛，就可以选择编辑器里预览时的语言了（黄色是不显示，绿色为当前显示的语言）

## 本地化 Label 文本

### 添加 Localize 组件

i18n 插件提供了两种组件分别用于配合 [Label](http://www.cocos.com/docs/creator/components/label.html) 和 [Sprite](http://www.cocos.com/docs/creator/components/sprite.html) 来显示多语言内容。

我们从 Label 开始，我们可以在场景或 prefab 中任何 Label 组件所在的节点上添加 `i18n/LocalizedLabel` 组件。这个组件只需要输入翻译数据索引的 dataID 就可以根据当前语言来更新 Label 的字符串显示。

下面我们来介绍如何配置 dataID。

### 翻译数据

插件创建的翻译数据模板是这样的：

```js
const win = window as any;

export const languages = {
    label_text: {
        hello: '你好！',
        bye: '再见！',
    },
};

if (!win.languages) {
    win.languages = {};
}

win.languages.zh = languages;
```

其中 `window.languages.zh` 全局变量的写法让我们可以在脚本中随时访问到这些数据，而不需要进行异步的加载。

如果像上面例子里一样设置我们的翻译数据，那么就会生成如下的键值对：

- "label_text.hello" : "你好！"
- "label_text.bye" : "再见！"

### 查看效果

接下来我们只要在 LocalizedLabel 组件的 `dataID` 属性里写入 `label_text.hello`，其所在节点上的 Label 组件就会显示 `你好！` 文字。

运行时如果需要修改 Label 渲染的文字，也请对 `LocalizedLabel.dataID` 进行赋值，而不要直接更新 `Label.string`。

当需要预览其他语言的显示效果时，打开 i18n 面板，并点击语言前方的小眼睛图标，切换语言，场景中的 Label 显示就会自动更新。

### 运行时设置语言

游戏运行时可以根据用户操作系统语言或菜单选择来设置语言，在获取到需要使用的语言 ID 后，需要用以下的代码来进行初始化：

```typescript
import * as i18n from 'db://i18n/LanguageData';
i18n.init('zh');
```

需要在之后动态切换语言时也可以调用 `i18n.init()`。

如果切换后需要马上更新当前场景，可以调用 `i18n.updateSceneRenderer()`。

注意运行时必须保证 `i18n.init(language)` 在包含有 LocalizedLabel 组件的场景加载前执行，否则将会因为组件上无法加载到数据而报错。

### 脚本中使用翻译键值对获取字符串

除了和 LocalizedLabel 配合使用解决场景中静态 Label 的多语言问题，`LanguageData` 模块还可以单独在脚本中使用，提供运行时的翻译：

```typescript
import * as i18n from 'db://i18n/LanguageData';
i18n.init('en');
let myGreeting = i18n.t('label_text.hello');
cc.log(myGreeting); // Hello!
```

## 本地化 Sprite 图片

### 添加 LocalizedSprite 组件

首先在场景或 prefab 中任何 Sprite 组件所在的节点上添加 `i18n/LocalizedSprite` 组件。该组件需要我们手动添加一组语言 id 和 SpriteFrame 的映射，就可以在编辑器预览和运行时显示正确语言的图片了。

### 添加语言图片映射

负责承载语言到贴图映射的属性 `spriteFrameSet` 是一个数组，我们可以像操作其他数组属性一样来添加新的映射

- 首先设置数组的大小，要和语言种类相等
- 为每一项里的 `language` 属性填入对应语言的 id，如 `en` 或 `zh`
- 将语言对应的贴图（或 SpriteFrame）拖拽到 `spriteFrame` 属性里。

完成设置后，点击下面的 `Refresh` 按钮，就可以在场景中看到效果了。

和 `LocalizedLabel` 一样，当我们在 i18n 面板设更改了预览语言时，当前场景里所有的 `LocalizedSprite` 也会自动刷新，显示当前语言对应的图片。
