i18n.lock 锁文件

i18n.lock 是一个锁文件，用于跟踪内容校验和，以防止不必要的重复翻译，并优化 Lingo.dev CLI 的性能。

i18n.lock 会存储源内容和翻译键的校验和，以识别每次翻译运行之间发生的更改。因此，只有新增或已修改的内容会被翻译，从而减少处理时间和翻译成本。

锁文件结构

i18n.lock 采用结构化 YAML 格式存储内容校验和：

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    key: f8692d39317193acf0e2e47172703c46
  b18975fb19122ebb67g0ef817641f553:
    key: g9703e40428204bdf1f3f58283814d57

配置元素：

  • version — 锁文件的 schema 版本，用于迁移兼容性
  • checksums — 内容校验和与键校验和的映射，用于跟踪已翻译内容
  • checksums.[content-hash] — 源内容的 SHA-256 哈希，作为唯一标识符
  • checksums.[content-hash].key — 翻译键的 SHA-256 哈希，用于检测键重命名

当检测到内容相同但键校验和不同的情况时，Lingo.dev CLI 会保留现有翻译。不会发生重新翻译，从而在允许键组织变更的同时保持翻译一致性。详细信息请参阅 键重命名。

工作流集成

i18n.lock 会在翻译工作流中自动运行：

首次运行 — 创建包含初始内容校验和的锁文件：

npx lingo.dev@latest run
# Creates i18n.lock with all source content checksums

重新创建锁文件 — 从头开始重新生成锁文件：

npx lingo.dev@latest lockfile --force
# Recreates i18n.lock with all source content checksums

提示：在解决合并冲突时，可以安全地使用此命令将锁文件重置为真实状态。每次加载时也会自动执行去重；详见 锁文件去重。

后续运行 — 仅处理已更改的内容：

npx lingo.dev@latest run
# Compares current content against i18n.lock
# Translates only new or modified content

强制重新翻译 — 跳过锁文件优化，重新翻译所有内容并重建锁文件：

npx lingo.dev@latest run --force
# Ignores i18n.lock and retranslates all content

冻结校验 — 验证翻译完整性：

npx lingo.dev@latest run --frozen
# Fails if any content requires translation
# Used in CI/CD to ensure complete translations

锁文件去重

锁文件 YAML 可能在同一校验和块下包含重复的翻译键。标准 YAML 解析器只保留最后一次出现的键，这可能导致跟踪丢失以及难以手动解决的合并冲突。

Lingo.dev CLI 旨在保持锁文件状态一致。每次加载时会自动对锁文件进行去重。会检测并移除校验和块下的重复键，仅保留最后一次出现的（最后写入优先，符合常见的合并行为）。因此，锁文件始终保持内部一致，并与写回的内容一致。

运行时机 — 每次加载时都会执行去重，包括：

  • npx lingo.dev@latest run
  • npx lingo.dev@latest pull
  • npx lingo.dev@latest push
  • npx lingo.dev@latest status
  • npx lingo.dev@latest lockfile

如果检测到重复项被移除，CLI 会记录类似 Removed 3 duplicate entries from i18n.lock 的日志信息。用户无需操作；该步骤具备幂等性，每次加载都可安全执行。对于难以解决或反复出现的合并问题，仍可使用 npx lingo.dev@latest lockfile --force 从头重建锁文件。

示例 — 合并两个都更改了相同键的分支后：

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.hello: abc123
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: ghi012
    button.submit: jkl345

加载时，CLI 会去重并保留每个键的最后一次出现：

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: jkl345

已移除两个重复项。

版本控制集成

i18n.lock 必须与翻译文件一起提交到版本控制系统中。

lockfile 是 Lingo.dev CLI 增量翻译系统的核心组件，使其能够高效支持任何规模的项目。