GitHub App

Lingo.dev GitHub App 使用 .lingo/config.json 为仓库启用持续本地化。

前置条件#

安装应用前，请先确认你已具备以下条件：

• 一个已启用 GitHub 集成功能的 Lingo.dev 组织
• 该组织中的一个本地化引擎
• 对要连接的 GitHub 组织或仓库拥有管理员权限

连接 GitHub App#

1. 在 Lingo.dev 中打开你的组织。
2. 进入 Settings。
3. 在集成区域找到 GitHub (App)。
4. 在 GitHub (App) 这一项中点击 Connect。
5. 在 GitHub 中，选择要安装此应用的账户或组织。
6. 选择 All repositories 或 Only select repositories。
7. 点击 Install。

安装完成后，Lingo.dev 会在 Settings > GitHub (App) 中显示已连接的 GitHub 账户和仓库。之后如果需要添加或移除仓库，可在同一设置卡片中使用 Manage repositories on GitHub。

如果你的安装请求仍在等待批准，GitHub 管理员可在 GitHub 组织的 Settings > GitHub Apps 中查看。GitHub 也会在组织设置中向组织所有者显示待处理的应用请求。

添加仓库配置#

在已安装此应用的仓库中创建 .lingo/config.json：

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de"],
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "docs/en/**/*.mdx" },
    { "pattern": "locales/en.json" }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": true }
    },
    "safety": {
      "requireApproval": false
    }
  }
}

文件模式#

files 模式用于指向源文件（默认区域设置文件）。应用会根据这些模式检查变更文件，并且只处理匹配且受支持的源文件。

这些模式相对于仓库根目录、区分大小写，并支持使用：

• * 匹配单个路径段内的内容
• **/ 匹配任意目录层级

模式不能以 / 开头，也不能包含 ..。

{
  "files": [
    { "pattern": "docs/en/**/*.md" },
    { "pattern": "src/content/en/**/*.mdx" },
    { "pattern": "messages/en.jsonc" }
  ]
}

文件选项#

files 中的每个条目除了自身的 pattern 外，还可以附带其他选项。所有选项均为可选，且各自只适用于特定格式。

translateComponentProps 条目既可以是 prop 名称（适用于任意组件或标签上的该 prop），也可以是一个对象，用于将 props 限定到指定组件或标签：

{
  "files": [
    {
      "pattern": "src/content/en/**/*.mdx",
      "translateFrontmatterFields": ["title", "description"],
      "translateComponentProps": [
        "alt",
        { "component": ["Callout", "Hero"], "props": ["title", "subtitle"] }
      ]
    },
    {
      "pattern": "locales/en.json",
      "lockedKeys": ["app.version"],
      "injectLocale": { "enabled": true, "key": "language" }
    }
  ]
}

本地化文件写入位置#

应用会根据源路径和配置中的区域设置代码推导出每个目标路径：

请使用完整的目录名或文件名作为区域设置代码。例如，如果源文件位于 docs/en-US/，应设置 "sourceLocale": "en-US"，而不是 "en"。如果源字符串位于 messages/en.json，则应设置 "sourceLocale": "en"。

当源路径包含区域设置目录时，应用会替换该目录；当源路径本身是以区域设置命名的文件时，应用会替换文件名。如果两种情况都不存在，应用会在源文件旁新建一个目标区域设置目录，并将翻译后的文件写入其中。

工作流#

推送到默认分支#

当默认分支上新增或修改了匹配的源文件时，应用会对其进行翻译，并将本地化文件提交到：

lingo/translations/<default-branch>

随后，它会从该翻译分支向默认分支发起新的拉取请求或更新现有拉取请求。如果翻译分支已存在，新提交会追加到该分支。

如果同一次推送中新增或修改了目标文件，应用会将这些文件视为已处理，并将其带入翻译 PR，而不是覆盖它们。

拉取请求#

当 github.workflows.onPullRequest.enabled 设置为 true 时，应用会检查拉取请求中的变更，查找匹配的源文件，并将翻译后的文件直接提交到 PR 分支。

应用不会写入 fork 的 PR 分支，也不会通过 PR 评论向默认分支写入内容。只有当拉取请求处于打开状态时，应用才会提交翻译。

在 PR 中，Lingo.dev 会更新一条评论，列出已翻译的文件以及所有失败信息。

增量更新与恢复#

对于已有的目标文件，应用只会翻译它能检测到的源内容变更，而不会重新生成整个文件。对于新的目标文件，它会为每个已配置的目标区域设置创建对应的本地化文件。

如果之前的 PR 本地化遗漏了某项源内容变更，或在更新目标文件前失败，下一次 PR 同步时可通过比对 PR 源内容与基础分支源内容来补回遗漏的变更并完成翻译。

如果在当前处理的提交中源文件已不存在，应用会跳过该文件。

审批模式#

如果你希望自动翻译运行前先经过人工审批，请将 github.safety.requireApproval 设置为 true。

对于默认分支上的推送，Lingo.dev check run 会显示 Approve 和 Deny 操作。对于拉取请求，应用会发布一条翻译提案评论；请回复：

/lingo approve

带作用域的 /lingo translate 命令无需经过此审批流程。

手动 PR 命令#

在拉取请求评论中使用 /lingo，即可为特定文件补齐翻译或强制触发翻译。

/lingo translate docs/en/**/*.md

/lingo translate docs/en/**/*.mdx --locales fr,es

/lingo translate docs/en/**/*.md --force

命令参考：

命令必须单独占一行。Glob 会与同时匹配你已配置的 files 源模式的文件进行匹配。与配置模式相同，命令 glob 不能以 / 开头，也不能包含 ..。

默认情况下，/lingo translate 以补齐模式运行：只会创建 PR 分支中缺失的目标文件。如需重新生成现有目标文件，请添加 --force。

支持的格式#

GitHub App 会根据文件扩展名识别以下格式：

• JSON（.json）
• JSONC（.jsonc）
• Markdown（.md）
• MDX（.mdx）
• Markdoc

同样支持以 YAML 编写的 OpenAPI 文档，但不会自动识别。请在文件模式上设置 "format": "yaml-openapi"：

{
  "files": [
    { "pattern": "openapi/en.yaml", "format": "yaml-openapi" }
  ]
}

大规模更新#

应用可能会将翻译输出拆分为多个提交。当一次运行需要在单个提交中写入超过 100 个文件，或翻译文件内容总量超过 5 MB 时，就会出现这种情况。

出现这种情况时，提交信息会包含批次编号，例如：

feat: Lingo.dev translations (1/3)
feat: Lingo.dev translations (2/3)
feat: Lingo.dev translations (3/3)

没有匹配项时会发生什么#

如果缺少 .lingo/config.json，应用会静默跳过该仓库。配置文件存在后，如果配置无效，则会生成失败的 check run；在 PR 中，还会附带一条包含校验错误的评论。

如果没有变更文件匹配你的源模式，应用会在不写入任何翻译的情况下完成运行。对于 /lingo translate，机器人会回复简短说明，例如没有匹配文件、没有匹配区域设置，或所有目标文件都已存在。

后续步骤#