本地化 Flutter 应用

翻译 ARB 消息,生成 Flutter 资源,并在各个目标语言区域下检查生成的界面。

Flutter 的本地化工具会将 ARB 消息转换为组件可调用的方法。Lingo.dev 负责翻译这些 ARB 资源,让你在添加新语言时,仍能沿用自动生成的 API。先从一个界面入手,利用其中的问候语和项目数量,同时检查文本、变量和复数处理是否正确。

本流程假设项目已通过 Flutter 的本地化生成机制加载源 ARB 文件。保留现有的 l10n.yaml、生成器和组件调用。这里,Lingo.dev 负责文件翻译,Flutter 则继续负责选择语言区域和呈现消息。

为每条消息提供所需信息 #

如果源文件位于 lib/l10n/app_en.arb,可以使用如下消息目录:

json
{
  "@@locale": "en",
  "welcome": "Welcome, {name}",
  "@welcome": {
    "description": "Greeting on the signed-in account screen",
    "placeholders": { "name": { "type": "String" } }
  },
  "itemCount": "{count, plural, =0{No items} =1{One item} other{{count} items}}",
  "@itemCount": {
    "description": "Number of items in the cart",
    "placeholders": { "count": { "type": "int" } }
  }
}

描述用于向译者说明消息的用途,占位符定义则告诉 Flutter 调用方会提供哪些值。ARB 处理器会翻译这两条消息字符串,保留元数据,并将现有的 @@locale 字段改为目标语言区域。

先对源文件运行项目的本地化生成器,再在界面中调用生成的问候语和数量方法。这样可以在引入另一种语言之前,确认原始消息目录与调用方一致。

在项目根目录下安装当前版本的 CLI,并完成身份验证:

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets de,fr --files 'lib/l10n/app_en.arb' --yes
lingo link

init 会写入 .lingo/config.json;link 用于选择组织和本地化引擎。保留生成的标识符。本地化字段应只匹配源文件:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    { "pattern": "lib/l10n/app_en.arb", "format": "flutter" }
  ]
}

这只是已关联配置中的本地化部分,不能替代其中的组织和本地化引擎 ID。.arb 扩展名还会自动选择 flutter。这种布局会生成 app_de.arb 和 app_fr.arb;请确认项目的生成器能够读取这两个文件。如果采用其他布局,请设置明确的目标路径。

避免使用 app_*.arb 这类也会匹配已翻译消息目录的源文件模式。对于带地区信息的语言区域,文件名写法应与 Flutter 项目的配置一致,不要假定所有语言区域字符串都能原样用于文件名。

翻译并生成目标资源 #

如果缺少目标文件,请运行:

sh
lingo push --backfill-missing --wait

该命令会等待运行完成并获取文件。如果运行正在等待审核或已经失败,请先处理这一状态,再生成发布资源。首次执行普通推送可以建立源内容基线,而不请求补齐这些缺失的翻译。

检查目标文件中的键、描述、占位符名称和类型,以及 @@locale。然后执行项目的 Flutter 本地化生成、分析、测试和构建。继续之前,请修复所有无效的 ICU 表达式、缺失的占位符或不兼容的类型。ARB 重建会保留元数据,但不会逐条验证翻译后的消息是否符合 Flutter 生成器的要求。

分别以德语和法语打开界面。先提供一个短名字和一个长名字,再分别测试 0、1、2 和一个较大的数量。不仅要检查数字是否显示,还要仔细阅读复数表述。目标语言可能需要英语源文本未涵盖的复数类别,因此请审核目标语言所需的形式。视情况检查语言区域选择、回退、文本长度变化和文本方向。日期和数字的格式仍由 Flutter 在运行时决定。

让后续更新始终与源内容关联 #

将配置、源文件、已接受的目标文件和 .lingo/lock.json 保存在一起。修改源消息后,运行 lingo push --wait,并将该消息与相邻的一条未修改消息对照检查。仅修改描述不会让消息文本自动成为新的翻译任务;如果更新后的上下文需要触发重新翻译,请使用限定范围的更新。

回写尚未完成时,不要编辑目标文件。要保护本地对目标文件的修正,提交时不要使用 --wait,先检查 lingo pull --dry-run,再在提交所用的 checkout 中通过 lingo pull 获取结果。其他机器需要已提交的翻译,或通过明确的交接获取产物,不能假定它们共享上一次运行。恢复详情请参阅保留已审核的翻译。

这套流程正常运转后,可以使用 GitHub App 或 CI 自动化,在审核前重复执行翻译和资源生成。原生 Android XML 和 Apple 资源采用不同的文件和运行时约定;在跨平台项目中,应将它们与 ARB 生成分开处理。