lingo push

将源文件推送到引擎，等待运行完成，并将结果写入磁盘。

lingo push [patterns...] [--force] [--backfill-missing] [--yes]

默认行为——增量推送#

不带任何参数时，lingo push 会以仅增量模式运行：

1. 为配置中 files 模式匹配到的每个源文件计算哈希
2. 将每个哈希与锁文件比对，找出发生变更的源文件
3. 将变更过的源文件作为一次运行上传到引擎
4. 等待这次运行完成
5. 将输出写入磁盘
6. 把新的源文件哈希提交到锁文件

如果自上次成功推送后没有任何源文件发生变化，命令会直接以 ✓ Nothing to push. 结束——无需与服务器往返，也不会消耗令牌。

参数与标志#

位置参数：patterns...——作用域推送#

lingo push docs/en/about.md
lingo push 'docs/en/**/*.md' 'locales/en.json'

将推送范围限制在特定文件上（必须匹配 .lingo/config.json 中已定义的模式）。这会让命令切换到作用域模式：

• 不再与上一次的源文件做差异比对——所有匹配到的源文件都会被视为在作用域内，即使没有改动。
• 对于已存在且源文件哈希一致的目标，服务端会执行 noop——引擎会跳过它们，CLI 会将其报告为已缓存。

适合在你只想翻译一个刚更新的文件、又不想重新为整个项目计算哈希时使用，或者想借助 --force 重新翻译单个页面时使用。

--force / -f#

lingo push docs/en/about.md --force

重新翻译每一个匹配的目标，忽略现有翻译并绕过服务端缓存。必须指定作用域——可以使用位置模式，也可以使用 --backfill-missing。单独使用 lingo push --force 会被拒绝，因为那会重新翻译整个项目。

默认情况下，--force 会在执行前提示确认：

! --force will retranslate every target for pattern(s): docs/en/about.md and
  overwrite existing translations. Continue? (Yes, retranslate / Cancel)

传入 --yes / -y 可跳过提示（适合 CI）。

--backfill-missing#

lingo push --backfill-missing

翻译所有尚不存在的目标文件，覆盖所有已配置模式。它等价于对配置里的全部模式执行一次作用域推送，但只生成缺失的文件。适用于在 targetLocales 中新增语言区域后，或新项目首次推送时使用。

与 --force 搭配使用，可从头重新翻译全部内容：

lingo push --backfill-missing --force --yes

--yes / -y#

跳过 --force 的确认提示。不与 --force 一起使用时无效。

输出#

成功时：

Pushing source files to localization engine…
✓ Run run_a8c...: localized 12 target file(s), 4 already up-to-date, uploaded 1 new artifact(s).

摘要会拆分为以下几类：

• 已本地化 N 个目标文件——引擎生成了新的翻译，CLI 已将其写入磁盘。
• N 个已是最新——命中服务端缓存（源文件一致，目标文件被复用）。
• 已上传 N 个新工件——这些源文件此前未被引擎见过（二进制/大体积内容只存储一次，后续通过引用复用）。
• 已跳过 N 个目标（本地有修改）——本地目标哈希与锁文件不一致。使用 --force 重新运行即可覆盖。

如果某个目标失败，CLI 会打印每个失败目标对应的错误信息，并以非零状态退出——这对 CI 很有用：

✓ Run run_a8c...: localized 10 target file(s).
  2 target(s) failed:
    locales/de.json: rate limit on engine; retry later
    locales/fr.json: timeout

重试机制#

锁文件只会在整次运行完全成功后更新。若发生部分失败（例如某个语言区域超时），锁文件中的源文件哈希不会变化，因此下一次执行 lingo push 时会重试相同的差异——无需手动重置。

如果引擎在任何翻译开始前就报错（例如认证或校验失败），则不会写入任何内容，锁文件也保持不变。

常见用法#

CI：合并后翻译#

- run: lingo push --backfill-missing --yes
- run: git add . && git commit -m "chore: refresh translations" && git push

--backfill-missing 是安全的默认选择：不会覆盖任何内容，只会补齐缺失项。

单文件迭代#

lingo push docs/en/onboarding.md -f -y

在文案发生较大改动后，只重新翻译一个源文件。跳过提示可加快迭代速度。

新增语言区域#

在 .lingo/config.json 中增加 targetLocales 后：

lingo push --backfill-missing

将整套内容翻译到新的语言区域，同时不会重新翻译已有内容。