处理已有翻译内容

Lingo.dev CLI 可无缝集成到已包含翻译文件的项目中，在补全缺失翻译的同时，保留现有成果。

当您在已有翻译的项目中运行 CLI 时，它会分析已完成的翻译，仅为缺失的键生成内容，从而保持现有翻译的质量和一致性。

注意：请确保目标语言文件为空，且不包含源语言内容。在目标文件中保留源语言内容属于不良实践，可能会干扰翻译流程。

工作原理

Lingo.dev CLI 会将您的源内容与现有目标文件进行比对，识别缺口。仅生成缺失的翻译，现有内容不会被修改。

示例场景：

// locales/en.json (source)
{
  "welcome": "Welcome to our app",
  "button.save": "Save",
  "button.cancel": "Cancel",
  "error.network": "Network error"
}

// locales/es.json (existing partial translations)
{
  "welcome": "Bienvenido a nuestra aplicación",
  "button.save": "Guardar"
}

运行 npx lingo.dev@latest run 只会生成缺失的翻译：

// locales/es.json (after CLI run)
{
  "welcome": "Bienvenido a nuestra aplicación",
  "button.save": "Guardar",
  "button.cancel": "Cancelar",
  "error.network": "Error de red"
}

您已有的 "welcome" 和 "button.save" 翻译内容将保持不变。

首次运行已有翻译项目

首次在已有翻译的项目中运行 Lingo.dev CLI 时，会基于当前状态创建 i18n.lock 文件。该锁文件用于跟踪已处理内容，确保现有翻译不会被重新生成。

工作流程：

  1. 初始扫描 — CLI 识别目标文件中的现有翻译
  2. 差异分析 — 将源键与目标文件比对，查找缺失翻译
  3. 翻译生成 — 仅创建缺失的翻译内容
  4. 锁文件生成 — 为所有源内容记录内容指纹

从传统翻译系统迁移

Lingo.dev CLI 可兼容任何工具生成的翻译文件，只要其遵循 JSON、YAML 或其他受支持的标准格式。

迁移步骤：

  1. 配置 i18n.json — 设置 bucket 模式以匹配现有文件位置
  2. 运行初始翻译 — CLI 会补全所有缺失的翻译
  3. 审核并提交 — 保留现有翻译，仅填补缺失内容

迁移示例：

// Your existing project structure
locales/
  en.json    (source)
  es.json    (partial translations from previous tool)
  fr.json    (partial translations from previous tool)

// i18n.json configuration
{
  "locale": {
    "source": "en",
    "targets": ["es", "fr"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

CLI 会保留您的现有文件结构和翻译内容。

处理翻译质量

现有翻译的质量可能低于 AI 翻译引擎生成的内容。Lingo.dev CLI 提供了在需要时刷新翻译的选项：

保留现有翻译：

npx lingo.dev@latest run
# Preserves all existing translations, fills in gaps

重新翻译指定语言：

npx lingo.dev@latest run --force --target-locale es
# Regenerates all Spanish translations

重新翻译指定 key：

npx lingo.dev@latest run --force --key error.network
# Regenerates just the error.network key across all languages

有关重新翻译的更多信息，请参见 重新翻译。

目标文件为空

如果您的目标文件为空或仅包含部分 key，Lingo.dev CLI 会将其视为部分翻译，并补全缺失内容。

示例：

// locales/de.json (empty target file)
{}

运行 CLI 后，该文件将成为包含所有源 key 翻译的完整文件。

锁文件初始化

首次运行时会创建一个 i18n.lock 文件，反映您当前的状态。这可以防止 CLI 重新翻译已存在的内容，即使这些内容最初不是由 Lingo.dev CLI 生成的。

该锁文件可确保现有翻译与新翻译在后续操作中保持一致。