文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>聊天互动（含 UI）>国际化语言>Flutter

Flutter

最近更新时间：2025-07-14 12:06:02

我的收藏

本页目录：

说明：
高级国际化多语言能力在 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, language); 即可。此处的 language 为 ISO 639-1 语言代码。示例如下：
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, language); 即可。此处的 language 为 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
完整版请见此处。

中国站
目录