翻译范围
选择文件和稳定键,并将增量更新、目标覆盖和主动刷新分别处理。
一次本地化更改可能涉及一个文件、一种语言或一组消息。CLI 对这些维度采用不同的选择方式:项目配置决定文件和目标语言区域;位置参数模式缩小文件范围,并影响任务规划;--key 则按稳定键选择消息。
文件范围影响任务规划 #
lingo push 'locales/en.json' --wait该模式会缩小已配置源文件的范围。对于源文件与目标文件分开的格式,此命令会创建缺失的目标文件,并保持现有目标文件不变,即使源文件已经更改。如果任务未包含某些已配置的语言区域,命令会保留现有源内容基线,让后续常规推送仍能处理这些修改。如果尚无基线,命令也可以将其初始化。
日常修改源内容时,请使用常规的 lingo push --wait。如果要在源文件与目标文件分开的格式中主动替换整个文件,请指定位置参数范围,并配合 --force 使用。请注意,强制操作会丢弃现有目标内容的上下文。XCStrings 目录仍可复用内嵌翻译;请参阅目录更新。目标始终由 targetLocales 指定;推送不提供 --locale 或 --target-locale 标志。
按稳定键刷新 #
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --wait重复使用 --key 可指定多个选择范围。键是以点号或方括号表示的路径,例如 checkout.title 或 items[0].title;选择一个对象会包含其下的所有字符串。因此,auth.login 会包含 auth.login.title,但不会选择 auth.login_url。* 表示一个完整路径段,[] 表示每个数组元素;auth.log* 这样的部分通配符会被拒绝。以 $. 或 $[ 开头的模式会直接作为 JSONPath 查询传入。请用引号括起通配符模式。
为旧版 CLI 编写的含 / 的模式也适用。包含 / 的模式只按 / 分隔,每个名称都作为一个整体处理:auth/login 与 auth.login 选择相同的键,common/error.message 则选择 common 下的键 error.message。legal/Terms%20of%20use 这样的百分号编码名称会被解码;不含 / 的模式会被视为点号路径,不会被解码。因此,单个编码名称应写成 JSONPath,例如 $['Terms of use']。由于所有含 / 的模式都会按此方式解析,名称中含 / 的键需要使用 JSONPath,例如 $.routes['/about'].title。在这种形式中,* 表示一个完整名称;末尾的 *(如 auth/*)会选择 auth 直接下属的值,但不选择其中嵌套的对象或数组,这与旧版 CLI 的行为一致。末尾的 /** 会涵盖其前面名称下的所有内容:auth/** 与 auth 相同,auth/*/** 还会涵盖 auth 下被 auth/* 排除的对象和数组。items/0 这样的数字会选择数组元素或对象键 "0",具体取决于文档结构。名称内部的通配符、非末尾位置的 **、方括号,以及 a//b 这样的空名称都会被拒绝。
| 格式 | 键范围 |
|---|---|
| JSON/JSONC、PHP、TypeScript、Java properties | 重新生成选中的字符串,包括源值未更改的字符串。 |
| YAML/根键 YAML | 按稳定键选择字符串,但选中的字符串若未更改,仍可复用现有翻译。 |
| gettext、ARB、Apple strings、XCStrings、CSV、Android、XLIFF | 不支持;--key 会报错并停止推送。 |
| Markdown、MDX、Markdoc、HTML、OpenAPI YAML、SubRip、纯文本、Apple stringsdict | 没有稳定键;会跳过并显示提示。 |
按键刷新要求目标文件已存在。缺失的语言区域和没有稳定键的格式会被跳过并显示提示,不会进行初始化。补齐操作只补齐缺失的普通文件,不会填补现有文件内部的缺项。添加 --force 不会改变按键范围进行的任务规划,也不会阻止 YAML 复用现有翻译。
无论通过 push --wait 还是单独的拉取操作获取刷新结果,按键刷新都不会改变完整源内容的基线。因此,尚未处理的普通源内容修改仍会在下一次常规推送中得到处理。
修改指导内容后刷新 #
编辑本地化引擎的术语表或规则不会改变源文件的字节内容,因此常规推送可能不会执行任何操作。对于 JSON、JSONC、TypeScript 和 PHP,请选择受影响的稳定键。对于 YAML,若要精准修正,可直接编辑目标文件;也可以先保存已接受的目标翻译,再使用限定范围的整文件 --force,且不带 --key,来重新生成翻译。请检查生成后的整个文件,因为这种替换也可能更改相邻消息。键控制决定重建时保留哪些源值或目标值,但不决定要处理哪些内容。
如果更改较大,请选择一个足够小、便于检查和恢复的范围,并在提交前进行估算。估算会上传所需文件并规划处理工作,但不会创建翻译任务。
重新翻译单个语言区域 #
对于每种语言使用独立文件的项目,请删除该语言的目标文件,再补齐缺失的文件。操作前,请先完成待处理的源内容更新,并保存已接受的翻译。按条件筛选的清除操作会保留其他语言的源内容基线和 Lockfile 条目。
对于配置中位于 locales/en.json 的源文件,先预览将要删除的法语目标文件:
lingo purge --locale fr --file locales/en.json检查列出的路径。如果这些确实是要删除的目标文件,请确认删除并创建缺失的翻译:
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --wait对于使用通配符的配置(例如 locales/en/*.json),请在两个清除命令中都通过重复使用 --file 选项传入具体的源文件路径。清除操作不会自行展开通配符。请包含所有需要重新生成法语目标文件的源文件,并在补齐前确认没有其他目标文件缺失:补齐操作会创建所有缺失的已配置目标文件。
完成后,请检查法语输出,并将其与更新后的 Lockfile 一起提交。其他语言的现有目标文件会保持不变。选择规则请参阅清除。此方法不适用于 XCStrings 目录,因为源内容和所有目标语言区域共用一个文件。