说明:
高级国际化多语言能力在 Chat UIKit 2.1.3 版本后有较大改进与变动。本文档所示为新版本的用法。请确保您项目依赖的 tencent_cloud_chat_uikit 高于 2.1.3 版本。
腾讯云 IM Flutter TUIKit 默认自带 英文/简体中文/繁体中文/日语/韩语 语言包,作为界面展示语言。
根据此文档指引,您可以使用默认语言包,也可使用自定义的高级国际化能力,包括新增语言、新增词条或修改现有词条翻译。
?
?
?使用自带语言及词条库
如果您的 App,需要的语言仅包括英语/简体中文/繁体中文/日语/韩语,且不需要新增词条或修改现有词条翻译,请参考本部分。
跟随系统语言
直接使用 TUIKit 即可,无需额外步骤。插件内部会跟随系统语言自适应。
预指定显示的语言
如果您需要在初始化时,手动设置 TUIKit 界面语言,请在
TIMUIKitCore.getInstance()
中调用init
方法时,传入需要的语言。import 'package:tim_ui_kit/tim_ui_kit.dart';?final CoreServicesImpl _coreInstance = TIMUIKitCore.getInstance();?final isInitSuccess = await _coreInstance.init(language: LanguageEnum.en, // 请在此处定义语言,枚举值见下方// ...其他配置);
语言可选项,枚举值为:
enum LanguageEnum {zhHant, //繁体中文zhHans, //简体中文en, // 英文ko, // 韩语ja // 日语}
实时动态修改
I18nUtils(null, "en");
使用自定义的高级国际化能力
如果您需要支持,除 英文/简体中文/繁体中文/日语/韩语 外的更多语言,新增词条或修改现有词条翻译,请参考本部分。
说明
1. 本方案仅适用于,目标语言为阅读方向为从左至右的语言。对于阅读方向从右至左的小语种,如阿拉伯语,请自行在 GitHub fork 一份我们的 Chat UIKit 源码,完成自定义左右镜像开发适配。
2. 高级国际化多语言能力在 Chat UIKit 2.1.3 版本后有较大改进与变动。本文档所示为新版本的用法。请确保您项目依赖的 tencent_cloud_chat_uikit 高于 2.1.3 版本。
工具安装及配置
在使用腾讯云 IM i18n 工具之前,您需要将工具包仓库 fork 到本地机器,并在项目的
pubspec.yaml
文件中设置工具包路径。请按照以下步骤操作:1. 访问本工具包的 GitHub 仓库:tencent-chat-i18n-tool??。
2. 单击仓库页面右上角的 “Fork” 按钮。这将在您的 GitHub 账户下创建一个仓库副本。
3. 将 fork 的仓库克隆到本地机器上的一个目录中。您可以使用以下 Git 命令执行此操作:
git clone https://github.com/<your-username>/tencent-chat-i18n-tool.git
将
<your-username>
替换为您的 GitHub 用户名。4. 在您项目的
pubspec.yaml
文件中,将 fork 的仓库的本地路径添加到dependency_overrides
部分:dependency_overrides:tencent_chat_i18n_tool:path: /path/to/your/local/repository
将
/path/to/your/local/repository
替换为本地机器上克隆的仓库的实际路径。现在,可以通过在您项目的根目录中运行主脚本来使用腾讯云 IM i18n 工具。
(可选)在您的项目中添加新词条
要在项目中添加新词条,即利用我们的国际化能力,将您项目中的词条进行国际化,您需要使用以下方法包装词条:
对于不带参数的词条,请使用
TIM_t("词条")
方法。例如:TIM_t("会话")
。对于带参数的词条,请使用
TIM_t_para("模板:{{option}}", "模板:$option")(option: option)
方法。TIM_t_para
支持从option1
到option10
的参数。例如:TIM_t_para("服务器错误:{{option8}}", "服务器错误:$option8")(option8: $option8)
(其中option8
是参数名)。目前暂时仅支持一个参数。在项目中应用这些方法可确保词条在多语言支持下被正确处理。
?
?
?开始进行自定义配置
按照以下步骤使用腾讯云IM i18n工具:
1. 运行工具
dart run tencent_chat_i18n_tool
。默认情况下,它将读取项目的pubspec.yaml
文件中指定的本地工具包路径。如果您想使用其他路径,可以在提示时输入。此步骤中,输入
Y
即可使用自动检测到的路径,如图中圈出所示。输入 n
即可按提示,指定使用特定的工具包本地路径。?
?2. 如果您在上一小节,在您的项目中,添加了新词条,我们需要将这些新词条注入工具包中。
选择选项 A(A. Add new language entries for internationalization. This action must be performed before adding new entries.),新增原始语言词条。本工具将提供两个方式来添加新词条:
选项1(1. Read new entries from the 'new_language_entries.txt' file in the project root directory.):从项目根目录中的
new_language_entries.txt
文件中读取新词条。您可以手动将想要添加的词条写入此文件,每行一个词条,然后选择此选项将它们添加到工具中。选项2(2. Scan the project code to extract new entries and update the 'new_language_entries.txt' file (currently supports Simplified Chinese only).):扫描项目代码以提取新词条并更新
new_language_entries.txt
文件(目前仅支持中文)。选择此选项后,工具将自动扫描指定目录(如lib
)中的 Dart 文件,并从中提取中文词条。此时,打开 new_language_entries.txt
文件并查看提取的条目。如有必要,请对条目进行编辑。如下图所示:?
?
?二次编辑确认完成后,按回车键,以继续进行。
本步骤执行如图所示。执行完成后,在下方打印,成功将新词条增加入工具内各语言的词条包。
?
?3. 再次运行工具并选择选项B(B. Retrieve the tool's built-in language entries, including JSON files for all supported languages, and save them to your project directory for further customization.)。工具将把所有支持语言的内置语言条目保存到项目目录中的 JSON 文件中。
?
?
?4. 打开位于
languages
目录中的 JSON 文件,并翻译每个文件底部的新条目。此时,您还可以根据 key 值定位特定词条,并修改各语言词条库中的翻译文本。但是,请不要删除不需要的词条。?
?
?5. (可选)如果您想添加对新语言的支持,请按照以下步骤操作:
打开项目中的
languages
目录。选择您熟悉的语言文件并复制一份。
将复制的文件重命名为
strings_${ISO_LANGUAGE_CODE}.i18n.json
,其中 ${ISO_LANGUAGE_CODE}
是您要添加的新语言的 ISO 代码(例如,对于法语,文件名为strings_fr.i18n.json
)。ISO 639-1 语言代码如本文附录所示。将新文件中的所有条目翻译成相应的语言。
?
?
?6. 再次运行工具并选择选项C(C. Inject your modified language JSON files for all languages back into the tool, allowing the updated configuration to take effect.)将您修改的语言 JSON 文件注入回工具。现在,更新后的配置将在您的项目中生效。
?
?完成这些步骤后,您所做的更改将应用于腾讯云 IM i18n 工具的本地副本。如果您想与他人合作或共享更改,可以将修改后的工具包源代码推送到内部 Pub 服务器或 Git 仓库。要在项目中使用更新后的工具包作为依赖项,只需在
pubspec.yaml
文件中更新工具包路径,使其指向在线仓库:例如:
dependency_overrides:tencent_chat_i18n_tool:git:url: https://github.com/<your-username>/tencent-chat-i18n-tool.git
此时,重新运行您的项目,您的自定义国际化能力即生效。
?
?
?选择界面展示语言
跟随系统语言
直接使用 TUIKit 即可,无需额外步骤。
预指定显示的语言
如果您需要在初始化时,手动设置TUIKit界面语言,请在
TIMUIKitCore.getInstance()
中调用init
方法时,传入需要的语言。import 'package:tim_ui_kit/tim_ui_kit.dart';?final CoreServicesImpl _coreInstance = TIMUIKitCore.getInstance();?final isInitSuccess = await _coreInstance.init(extraLanguage: "ja", // 请在此处定义语言,ISO 639-1 语言代码 见下方// ...其他配置);
实时动态修改
I18nUtils(null, "ja");
后续更新说明
本
Tencent Cloud Chat i18n
工具包将与 Tencent Cloud Chat UIKit
同步更新,以保持版本一致性。在每次更新时,我们会将 Chat UIKit
新版本中的新增词条添加到此工具包中。所有更新都将在 pub.dev
和 GitHub 仓库中同步发布。如果您已将此工具包 fork 至自己的 GitHub 账户,请注意在每 次
Chat UIKit
更新时,您需要通过 pull upstream
操作将本工具包的最新词条库同步更新至您 fork 的版本中。这样可以确保您的 fork 版本既包含您自己添加或修改的词条,也包含我们在每个版本中新增的词条。在合并代码和解决冲突时,请确保各个 JSON 词条库保持完整。若合并后的 JSON 文件无法直接使用,您可以按照上文步骤 7 的指示重新运行程序,并选择 C 选项以使更新生效。请注意,在执行 C 选项之前,需要确保每个语言的词条 JSON 都是完整且无误的。
?
以下是一个
pull upstream
的 Git 操作示例:1. 首先,在您的本地仓库中添加上游(upstream)远程仓库:
git remote add upstream https://github.com/TencentCloud/tencent-chat-i18n-tool.git
2. 拉取上游仓库的最新更改:
git fetch upstream
3. 将您的本地仓库切换到要更新的分支(例如
main
或master
):git checkout main
4. 将上游仓库的更改合并到您的本地仓库:
git merge upstream/main
5. 如果有冲突,请在编辑器中解决它们,确保各个 JSON 词条库是完整的。
6. 提交解决冲突后的更改:
git add .git commit -m "Merge upstream changes and resolve conflicts"
7. 将更改推送到您的远程仓库:
git push origin main
现在,您的 fork 版本已经包含了最新的词条库。如果需要让更新生效,请按照上文中的步骤7重新运行程序,并选择 C 选项。
附录:语言代码表
语言 | 代码 | 语言 | 代码 |
阿拉伯语 | ar | 保加利亚语 | bg |
克罗地亚语 | hr | 捷克语 | cs |
丹麦语 | da | 德语 | de |
希腊语 | el | 英语 | en |
爱沙尼亚语 | et | 西班牙语 | es |
芬兰语 | fi | 法语 | fr |
爱尔兰语 | ga | 印地语 | hi |
匈牙利语 | hu | 希伯来语 | he |
意大利语 | it | 日语 | ja |
朝鲜语/韩语 | ko | 拉脱维亚语 | lv |
立陶宛语 | lt | 荷兰语 | nl |
挪威语 | no | 波兰语 | pl |
葡萄牙语 | pt | 瑞典语 | sv |
罗马尼亚语 | ro | 俄语 | ru |
塞尔维亚语 | sr | 斯洛伐克语 | sk |
斯洛文尼亚语 | sl | 泰语 | th |
土耳其语 | tr | 乌克兰语 | uk |
中文(简体) | zh-Hans | 中文(繁体) | zh-Hant |
联系我们
?