静态内容本地化

Lingo.dev CLI 可通过已配置的 本地化引擎 翻译仓库中的静态文件——包括 Markdown、MDX、Markdoc、JSON、YAML、字幕等。只需指向你的内容，运行一次，即可在源文件旁生成对应的译文文件。

支持的内容类型#

CLI 会根据文件扩展名自动识别格式，无需配置 bucket 类型。locale 信息直接体现在路径中（content/en/x.md 会变成 content/de/x.md），因此不需要 [locale] 占位符。

支持的文件类型完整列表，请参阅 格式参考。

前置条件#

每次运行时，内容都会经过一个本地化引擎——它的配置将决定采用哪个 LLM 模型、术语表、品牌语调和规则。先在 Lingo.dev 控制台中创建一个，再设置 CLI（Node 22+）：

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

lingo init 和 lingo link 会创建 .lingo/config.json，将 CLI 连接到你的组织和引擎。请提交这个文件，让所有环境共享同一份配置。

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "docs/en/getting-started.md" }]
}

在 CI 中，请跳过 lingo login，改为通过环境变量提供 LINGO_API_KEY。你可以在 API keys 中生成它。

文档站点#

大多数文档框架都会按 locale 目录组织译文内容。请在 files 中为每个源文件添加一个模式（或直接使用 glob）。CLI 在翻译 Markdown、MDX 和 Markdoc 时，会保留 frontmatter、代码块和组件语法不变。

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "docs/en/getting-started.md" },
    { "pattern": "docs/en/setup.mdx" }
  ]
}

运行首次翻译，回填所有目标 locale：

lingo push --backfill-missing

后续运行时，lingo push 只会翻译发生变化的内容。使用 lingo pull 可拉取在其他地方生成的翻译。

根据你的框架目录约定，调整源路径：

结构化数据#

JSON 和 YAML 文件会根据扩展名自动识别并翻译。使用 键控制 可以避免不可翻译的值（如 ID、URL、配置标记）被改动。

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "content/en.json" },
    { "pattern": "data/en.yaml" }
  ]
}

通用 YAML 无需 format 字段。只有 yaml-openapi、yaml-root-key 和 android 需要在文件条目中显式指定 "format"。

字幕#

SRT 字幕文件会根据扩展名自动翻译。CLI 会保留所有时间数据、字幕序号和格式标签——只有文本内容会被翻译。

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "subs/en/intro.srt" }]
}

处理大型内容#

静态内容仓库中可能包含成千上万个文件，CLI 也能高效应对：

如果你想在不写入文件的情况下验证翻译是否已是最新状态（非常适合作为 CI 门禁），请运行 lingo check。

后续步骤#