# 国际化

# 环境要求

USV 0.6.0 新增了国际化翻译的支持

要支持国际化的话

需要 USV 0.6.0 以上的 uCode 版本支持
@ubtech/ucode-extension_common-sdk 1.4.0 以上
@ubtech/ucode-extension-developer-kit 1.2.0 以上

# 使用教程

脚手架支持

推荐使用最新脚手架 1.3.2 以上的版本, 在特性里面启用翻译支持, 会内置翻译的模板

? 要集成的特性
 ◯ 串口协议 SerialPort
 ◯ 蓝牙协议 Ble
 ◯ UDP/TCP协议 UDP/TCP
 ◯ 烧录模式
 ◯ 自定义 UI 组件 *(Beta)
❯◯ 国际化支持

如果你想手动添加支持, 参照以下教程:

# 环境准备

首先先升级 uCode, sdk, developer Kit 到对应的版本

# 在代码中使用翻译

代码使用包括 js jsx ts tsx 等

插件初始化的时候, 在插件全局上下文里面注入了一个翻译格式化函数 self.UCode.formatMessage:

/** TypeScript 类型定义 */

type IntlMessage = {
  id: string;
  defaultMessage: string;
  description?: string;
};

type formatMessage = (msg: UBT.IntlMessage): string;

准备 message 消息文件

代码模板 (两种使用方式):

使用变量 formatMessage (区分大小写)
直接使用 self.UCode.formatMessage

在代码里面引用 message.ts 或者 message.js

import Messages from './message'; // 引用 message.js 或者 message.ts
/** 积木盒子名字使用翻译 */
  {
    // Category Define
    name: Messages.categoryName,
    iconURI: CategoryIcon,
    color1: '#0FBD8C',
    color2: '#0DA57A',
    color3: '#0B8E69',
  }

也可以直接在代码直接调用 self.UCode.formatMessage

案例:

/** 积木盒子名字使用翻译 */
  {
    name: self.UCode.formatMessage({
    id: 'category.name',
    defaultMessage: '标题',
  }),
    iconURI: CategoryIcon,
    color1: '#0FBD8C',
    color2: '#0DA57A',
    color3: '#0B8E69',
  }

# manifest.json 中使用翻译

manifest.json 由于不是代码里面使用, 因此 Manifest 的翻译, 直接按照 IntlMessage 的格式写即可

目前支持翻译的字段:

name
description
author

字段同时支持字符串或者 IntlMessage

{
  "id": "41384f96-76c1-4faa-af25-4b198532fb2d",
  "version": "0.0.2",
  "type": "hardware",
  "supportModes": ["online"],
  "icon": "logo.svg",
  "USV": "0.3.0",
  "name": {
    "id": "manifest.name",
    "defaultMessage": "串口测试",
    "description": "Manifest 插件名字"
  },
  "description": 
  {
    "id": "manifest.description",
    "defaultMessage": "这是一个demo",
    "description": "插件描述"
  },
  "author": {
    "id": "manifest.author",
    "defaultMessage": "你的名字",
    "description": "插件作者名字"
  }
}

# 翻译文件目录结构

插件项目源文件目录结构
├── dist
│   ├── logo.svg
│   ├── main.js
│   ├── main.js.map
│   └── manifest.json
├── i18n (翻译目录)
│   ├── dist (生成ucdext最终引用的路径)
│   │   ├── en-us.json
│   │   └── zh-cn.json
│   └── source (开发者套件提取的翻译中间文件)
│       └── zh-cn.json
├── package.json
└── ......

把翻译按照如下路径, 存放

i18n/dist/{locale}.json

生成插件的时候, 会自动把翻译文件加载进 ucdext里面

生成 ucdext 目录结构
ucdext
├── i18n
│   ├── en-us.json
│   └── zh-cn.json
├── logo.svg
├── main.js
└── manifest.json

# 翻译文件格式

翻译的文件以 json 格式, {key:value} 的形式.

下面是翻译文件的格式

{
  "block.test-send": "发送消息: [TEXT]",
  "block2": "block2 的标题",
  "block3": "block3 的标题",
  "category.name1": "积木盒子",
  "manifest.author": "你的名字",
  "manifest.description": "这是一个demo",
  "manifest.name": "翻译测试插件",
  "title": "标题"
}

# 翻译提取

只要按照以上的目录结构和翻译格式, 插件就可以支持翻译

但是翻译的提取需要手动准备会稍微比较麻烦, 因此 @ubtech/ucode-extension-developer-kit 内置了翻译提取的工具, 会同时提取代码翻译和Manifest翻译

在 package.json scripts 添加一行:

"i18n": "cua-i18n-extract"

执行

📢 注意: 翻译提取路径

默认情况下:

代码翻译是提取: src 下的所有代码文件, 包括: *.js *.jsx *.ts *.tsx
Manifest翻译提取的是: static/manifest.json

如果你需要改变默认路径, 可以使用 --help 查看帮助

执行完以后, 可以看到 i18n 目录下已经生成了最新的翻译

# 提供给翻译人员

把提取出来的翻译文件 i18n/dist/zh-cn.json 提供给翻译人员, 然后按照对应的 locale 命名文件

例如, 通用英语提供 en.json 或者北美英语 en-us.json

后期开放平台会开放 weblate 翻译工具, 专门用于提供给翻译人员的翻译一套翻译系统

📢注意: 积木块名字

另外要特别注意, 积木块的文案是带有占位符, 如果占位符不正常会导致积木块生成失败

例如:

  "block.test-send": "发送消息: [TEXT]",

[TEXT] 就是参数 TEXT 的占位符, 翻译的时候必须保证这部分占位符正常, 否则积木块会生成失败

← 自定义 UI (Beta) 和 Blockly、Scratch 的关系 →