多语言系统(i18n)

什么是 i18n

i18n(其来源是英文单词 internationalization 的首末字符 i 和 n ,18 为中间的字符数)是“国际化”的简称。

在资讯领域,i18n 指让产品(出版物,软件,硬件等)无需做太多改变就能够适应不同的语言和地区的需要。

在程序开发领域,i18n 则是指在不修改内部代码的情况下,能根据不同语言及地区显示相应的本地化内容。

Cocos Creator 扩展系统中内置的多语言方案(i18n)允许扩展配置多份语言的 键值映射,并根据编辑器当前的语言设置在扩展里使用不同语言的字符串。

注意:本文将介绍如何赋予 扩展 多语言的能力,如需在工程内添加运行时的多语言能力,请参考:

  1. 多语言本地化(L10N)
  2. i18n 游戏多语言支持

i18n 文件夹

要启用多语言功能(以下简称 i18n),需要在扩展的目录下新建一个名叫 i18n 的文件夹,并为每种语言添加一个相应的 JavaScript 文件,作为键值映射数据。

数据文件名应该和语言的代号一致,如 en.js 对应英语映射数据,zh.js对应中文映射数据。如下图所示:

i18n-folder

映射以 JavaScript 对象的 key 作为键值,并以模块信息导出,如下所示:

  • en.js

    1. "use strict";
    2. module.exports = {
    3. open_panel:"Default Panel",
    4. send_to_panel:"Send message to Default Panel",
    5. description:"Extension with a panel"
    6. };
  • zh.js

    1. module.exports = {
    2. open_panel:"默认面板",
    3. send_to_panel:"发送消息给面板",
    4. description:"含有一个面板的扩展"
    5. };

open_panel 为例,假设注册的扩展名字叫做 first-panel,则对应的文本翻译 key 为 first-panel.open_panel

在脚本中使用

在 TypeScript 或者 JavaScript 脚本中,可通过 Editor.I18n.t 接口获取当前语言对应的翻译后的文本:

  1. let str = Editor.I18n.t('first-panel.open_panel');

在 HTML 模板中使用

在 HTML 模版里需要翻译的话可以使用 ui-label 元素进行翻译:

  1. <ui-label value="i18n:first-panel.open_panel"></ui-label>

注意ui-label 是一个普通的行内元素,类似 span。

在 json 文件中使用

例如在扩展包的 package.json 中注册菜单路径时,只要这个字段支持 i18n 格式的路径,该路径就可以用 i18n:${key} 的形式实现多语言翻译功能。

示例1:扩展描述

  1. // "package_version": 2,
  2. // "version": "1.0.0",
  3. // "name": "first-panel",
  4. "description": "i18n:first-panel.description",
  5. // "main": "./dist/main.js",

示例2:面板标题

  1. "panels": {
  2. "default": {
  3. "title": "first-panel Default Panel",
  4. // "type": "dockable",
  5. // "main": "dist/panels/default",
  6. // "size": {...}
  7. }
  8. },

示例3:菜单路径与显示内容

  1. "menu":[
  2. {
  3. "path": "i18n:menu.panel/first-panel",
  4. "label": "i18n:first-panel.open_panel",
  5. "message": "open-panel"
  6. },
  7. {
  8. "path": "i18n:menu.develop/first-panel",
  9. "label": "i18n:first-panel.send_to_panel",
  10. "message": "send-to-panel"
  11. }
  12. ]