将 Android 应用本地化
翻译 Android 资源,将其放入对应的语言区域目录,并在应用中验证文本。
Android 会从资源目录中选用本地化文本,应用代码则继续使用原有的资源名称。Lingo.dev 将这些资源翻译后写入目标目录。初次尝试时,不妨从默认资源文件中选取一条问候语、一个列表和一项复数资源,让它们显示在使用另一语言区域的应用界面上。
此流程适用于原生 Android XML。使用 Flutter 时,请参阅 ARB 资源与生成的本地化代码;使用 JSON 文本目录时,请参阅 React Native 本地化。
准备界面需要加载的资源 #
将默认资源保存在 app/src/main/res/values/strings.xml 中:
<resources>
<string name="welcome">Welcome, %1$s!</string>
<string name="product_name" translatable="false">ExampleApp</string>
<string-array name="delivery_options">
<item>Standard delivery</item>
<item>Express delivery</item>
</string-array>
<plurals name="items_count">
<item quantity="one">%d item</item>
<item quantity="other">%d items</item>
</plurals>
</resources>通过应用现有的资源调用,将这些资源接入界面。welcome 用于标识文本;%1$s 接收代码传入的姓名。复数资源需要根据数量选择相应形式并进行格式化。translatable="false" 可将产品名称排除在翻译范围之外。
Android 文件处理器会选取纯文本条目,跳过混有内联子元素标记的条目。如果文本包含 <b> 或 <xliff:g> 等子元素,请单独处理这些条目。CDATA 文本可以在保留外层结构的同时进行翻译;其中的标记会被视为文本,而不是受保护的子元素结构。请使用应用实际采用的渲染器检查富文本资源。
配置源文件选择与语言区域路径 #
在项目根目录下安装并关联 CLI:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,pt-BR,zh-Hans --files 'app/src/main/res/values/strings.xml' --yes
lingo link在 .lingo/config.json 中保留已关联的组织和本地化引擎 ID,然后明确指定文件格式:
{
"pattern": "app/src/main/res/values/strings.xml",
"format": "android"
}将该对象用作文件条目。仅凭 .xml 扩展名无法区分 Android XML 与其他 XML 格式。为其他资源文件(例如 arrays.xml)添加源文件条目,但不要纳入生成的目标目录。
当前 CLI 可识别不带限定符的 values/ 目录,并为目标路径生成 Android 限定符:
| 目标语言区域 | 目标目录 |
|---|---|
es | values-es |
pt-BR | values-pt-rBR |
zh-Hans | values-b+zh+Hans |
这种目录布局不需要 values-en 符号链接。如果旧配置使用了该链接,请先更新并检查配置,再移除链接。直接使用 values-pt-BR 这样的目录名,不符合预期的区域限定符格式。CLI 配置介绍了如何明确指定目标路径,以及语言区域的写法。
翻译并加载第一个目标语言区域 #
如果目标文件尚不存在,请运行:
lingo push --backfill-missing --wait等待运行及所有已配置的审核完成,然后检查取回的 XML。对照源文件检查资源名称、数组顺序、数量属性、保持不变的产品名称和格式说明符。如果未使用 --wait,请在发起提交的 checkout 中通过 lingo pull 取回已完成的运行结果。
使用项目的 Gradle 配置构建应用,然后在设为目标语言区域的设备或模拟器上运行。打开界面,输入一个姓名,并测试几个不同的数量。构建成功可以验证资源语法和引用;设备上的检查则能确认 Android 是否确实选用了翻译后的目录。
选用能覆盖目标语言各复数类别的数量值,检查对应输出。处理器会保留源文件的复数结构,因此英语中的 one 和 other 并不意味着目标语言的复数形式已完整覆盖。请检查较长的标签、无障碍文本,以及需要时的从右到左布局。lingo check 不能替代 Android 资源检查或完整性检查。
继续处理源文本变更 #
将源文件、已接受的目标文件、已关联的配置和 .lingo/lock.json 一并提交。编辑源字符串后,使用以下命令翻译变更:
lingo push --wait修改引擎指导规则后,如需重新生成某个源文件的全部翻译,请先保存已接受的目标文件,再运行:
lingo push "app/src/main/res/values/strings.xml" --force --wait这会替换所选文件在已配置目标语言区域中的翻译。有关文件选择和重新生成的说明,请参阅 CLI 范围。
保留目标文件更新前后的差异记录。如上面的产品名称示例所示,使用 translatable="false" 标记需要保持不变的 Android 资源。刷新前,请先保存已有的修正。要检测提交后对目标文件所做的编辑,请省略 --wait,并在取回结果前检查 lingo pull --dry-run。保留已审核的翻译介绍了这项检查和冲突处理方式。
一个界面验证通过后,即可使用 GitHub App 或 CI 运行器定期执行翻译。运行器负责身份验证和可供审核的回写;接受结果前,仍需完成 Android 构建和有代表性的界面检查。在其他位置提交的翻译会通过版本控制同步,而 lingo pull 则用于取回本地记录的提交结果。