Angular 项目怎么实现国际化
Opened this issue · 0 comments
一个项目支持国际化一般会需要以下步骤:
- 根据项目代码提取需要翻译的文本
- 把文本上传到 TMS ,也就是翻译管理系统,进行翻译
- 把翻译后的文本同步到项目代码中,或者在打包时才去拉取,项目本身不维护其它语言文本
关于 TMS
Do You Really Need a Translation Management System? - Rubric 这里有对 TMS 的介绍。简单来说, TMS 是关于国际化的流程的工具,比如你可以通过命令行来上传文件,你可以在界面上先一键机器翻译,然后再校对和审核,可以在界面上指派翻译人员和查看翻译进度,最后可以通过命令行来下载文件。
现在各种 TMS 很多,比如 A Comparison of the 15 Best Translation Management Systems - Rubric 这里列举了 15 个。由于选项太多,并且无 TMS 使用经验,短时间内无法一一分析各自优缺点,所以我们选一个看起来没坑的即可,比如 Crowdin 。
在 Projects search - Crowdin 上面也可以发现一些你知道的应用,比如:
- Jest v2 translations in Crowdin
- Minecraft translations in Crowdin
- Microsoft MakeCode translations in Crowdin
Angular 项目实施国际化的大概步骤
第一步,在代码中标记哪些是需要国际化的
先 ng add @angular/localize
,然后再用 i18n
i18n-xxx
$localize
标记代码,详见 https://angular.io/guide/i18n-common-prepare ,下面是几个简单例子。
<div class="xsp-h1-title" i18n>Welcome to SuiteSpot™</div>
<img src="./logo.png" i18n-title title="Angular logo" />
title = $localize`hello world`;
<div>{{ title }}</div>
第二步,生成待翻译文件
使用 ng extract-i18n
即可生成,详见 https://angular.io/guide/i18n-common-translation-files#extract-the-source-language-file 。
第三步,集成 Crowdin ,用命令行上传源语言文件和下载翻译后文件
详见 https://support.crowdin.com/cli-tool/ 。
先在 Crowdin 上创建一个项目,然后在界面的 Tools - API
可以看到一个 Project Id 值,后面会用到。
还要去账号的 Settings - API
生成一个 token ,然后把环境变量 CROWDIN_PERSONAL_TOKEN 的值设为这个 token 。
然后 npm i @crowdin/cli
,然后在 package.json
的 scripts
中补充 "crowdin": "crowdin"
,然后执行 npm run crowdin -- init
来生成一份初始配置,初始化时选择不授权,后面通过增加配置项 "api_token_env" : "CROWDIN_PERSONAL_TOKEN"
来从环境变量中读取 token 。
然后再配置下 crowdin.yml 的 source 和 translation 即可,如下是一个示例。
# 上传时,源语言所在路径
"source" : "/src/i18n/en-US/*",
# 下载时,翻译的语言存放的路径
"translation" : "/src/i18n/%locale%/%original_file_name%",
然后就可以 npm run crowdin -- upload
来上传文件了,然后 npm run crowdin -- download
来下载翻译后的文件。
补充, Crowdin 支持一键机器翻译,也支持每次上传新内容时自动先机器翻译,详见 Pre-Translation via Machine | Crowdin Documentation 。
第四步,打包时生成多份语言对应的包
修改 angular.json
,在 architect.build.configurations.production
下增加 "localize": true
,然后在 projects.xxx
下增加:
"i18n": {
"sourceLocale": "en-US",
"locales": {
"zh-CN": "src/i18n/zh-CN/messages.xlf",
"es-ES": "src/i18n/es-ES/messages.xlf",
"fr-FR": "src/i18n/fr-FR/messages.xlf"
}
}
然后再参照 Internationalization | NG-ZORRO 来配置 antd 的国际化。
这样配置完后,本地开发是默认语言,打包后是多种语言。打包后目录如下所示,一个语言对应一个目录。
其它资料
- Jest 官网的打包流程: https://github.com/facebook/jest/blob/v28.1.0/website/package.json#L14
- Docusaurus 对 Crowdin 的一些使用经验: https://docusaurus.io/docs/i18n/crowdin
- 国际化与本地化 中的
本地化的挑战主要有不同地域的语言、文化、书写习惯及法律方面的差异带来的问题
部分
Docusaurus 文档上不建议把翻译后的文件保存在代码仓库中,因为 Crowdin 对并发的上传/下载支持不够好。
Crowdin does not support well multiple concurrent uploads/downloads: it is preferable to only include translations to your production deployment, and keep deploy previews untranslated.
所以我们实际应用时,想稳妥点的话,就是在打包时才去上传和下载,可以参照 Jest 官网的打包命令,先执行 netlify:crowdin
来同步 crowdin 数据再 yarn build
"netlify:ci:production": "yarn netlify:prepare && yarn netlify:crowdin && yarn build",
"netlify:prepare": "yarn fetchSupporters && yarn build:js",
"netlify:crowdin": "yarn write-translations && yarn crowdin:upload && yarn crowdin:download"