GitHub

使用 GitHub App 翻译仓库内容,让源内容变更和翻译结果都可供审核。

Lingo.dev GitHub App 将翻译文件纳入仓库的变更历史。你只需提交源内容和翻译配置,应用就会读取选定文件,通过本地化引擎完成翻译,并返回可供团队在 GitHub 中检查的差异。

在 Studio 2.5 的导航中,请打开 Studio 2.5 → 集成,而非 设置 → 集成。现有的连接和配置链接仍可正常使用。

默认分支上的变更会生成翻译拉取请求。如果启用拉取请求处理,翻译则会提交到该拉取请求的分支。本页先介绍默认分支工作流,并将翻译交付与是否合并的决策分开说明。如需在自己的运行器中运行 CLI,请参阅 GitHub Actions 配置指南。

如需让你的编程智能体连接到应用,请参阅通过编程智能体完成设置。

连接仓库与翻译配置 #

在 Lingo.dev 中,打开设置 → 集成,选择 GitHub 对应的连接。将已安装的应用关联到你的组织,并授予其访问待处理仓库的权限。安装可能需要 GitHub 组织管理员批准;仓库访问权限以安装时选择的范围为准。

在已连接的组织中,选择一个你有权访问的本地化引擎。引擎配置决定所用模型、术语表、规则、品牌语调及适用的审核行为。GitHub 安装权限控制仓库操作权限;Lingo.dev 权限控制本地化引擎的使用权限。

在设置 → 集成中打开该连接,查看应用安装情况和连接状态。点击在 GitHub 上管理可打开该安装的仓库访问设置。在 Studio 中,从已连接下选择仓库,再结合工作流运行、GitHub 检查和提交记录,跟踪某次源内容变更。

如果你的组织已启用 Studio 2.5,源内容侧边栏会直接列出已连接的应用安装可访问的仓库,无需等待 GitHub 事件。只要默认分支上有有效的 .lingo/config.json,就能打开已配置的 JSON 和 JSONC 源文件及其现有翻译,无需新提交或启动翻译运行。浏览不会消耗翻译额度,也不会启用自动同步。配置无效的仓库仍会显示;打开其文件时会提示配置错误。

在仓库根目录创建 .lingo/config.json。以下示例选取 locales/en/ 下的英语 JSON 文本目录,并在对应的 locales/fr/ 路径下生成法语文件。请将 eng_example 替换为你的本地化引擎 ID:

json
{
  "engineId": "eng_example",
  "sourceLocale": "en",
  "targetLocales": ["fr"],
  "files": [
    {
      "pattern": "locales/en/**/*.json",
      "format": "json"
    }
  ],
  "github": {
    "workflows": {
      "onPushToDefaultBranch": { "enabled": true },
      "onPullRequest": { "enabled": false }
    },
    "safety": { "requireApproval": true }
  }
}

完成一次运行并检查结果 #

此示例要求先获得批准,再开始翻译。测试步骤如下:

  1. 将配置和一处小范围源内容变更提交到默认分支,例如修改 locales/en/checkout.json 中的一条消息。
  2. 打开待处理的 GitHub 检查,批准此次运行。如果无法批准,请检查批准规则。
  3. 打开应用创建或更新的翻译拉取请求。找到 locales/fr/checkout.json,将变更后的消息与源内容对照检查。
  4. 使用翻译文件构建或运行应用程序。检查措辞、变量和语言区域选择,再按仓库的常规流程审核并合并拉取请求。

第 2 步的批准仅授权执行翻译工作并产生相应用量,不代表认可翻译措辞,也不会合并拉取请求。如果缺少输出,请参阅检查与恢复,找出尚未完成的阶段。

根据文件布局调整配置 #

源文件匹配模式应仅选取源文件。例如,locales/en/**/*.json 可避免后续扫描源文件时选中已生成的法语文件。匹配模式使用相对于仓库根目录的路径;绝对路径和 .. 会被拒绝。每个文件条目都必须提供 pattern 或 include 列表。每份配置最多支持 100 个文件条目和 50 个不同的目标语言区域。

默认情况下,路径中的源语言区域决定目标文件的存放位置。如果路径中不含语言区域,请设置 targetPath:[locale] 指定目标语言区域,[path] 指定移除可选的 sourceRoot 前缀后的源路径。例如,针对法语,sourceRoot: "content" 和 targetPath: "translations/[locale]/[path]" 会将 content/help/start.md 映射到 translations/fr/help/start.md。基于通配模式的模板必须同时包含这两个占位符。sourceRoot 需要设置 targetPath,且必须是所选源路径的前缀。Xcode 字符串目录和 CSV 等在单个文件中存储多个语言区域的格式不支持输出模板,因为译文保存在原文件中。

如果应用程序的路径需要采用 BCP-47、下划线分隔或 Android 语言区域写法,请使用 localeFormat。Android 资源默认采用 Android 限定符。添加更多语言区域前,请先确认首个输出路径与应用程序的加载器兼容。

选择翻译运行时机和写入位置 #

默认分支的推送处理默认启用。拉取请求处理默认禁用,需在配置中显式启用。

启用拉取请求处理前,请先将有效的 .lingo/config.json 提交到默认分支。应用会从这一受信任的默认分支修订版本中读取引擎 ID、github.workflows 和 github.safety。在拉取请求中修改这些设置,并不能授权该请求自身的运行使用其他引擎,也不能改变该运行的批准策略。源语言区域、文件选择和目标语言区域则取自正在翻译的修订版本。

触发条件翻译交付方式
推送到默认分支提交到 lingo/translations/<default-branch>,并创建或更新以默认分支为合并目标的拉取请求。
已启用的拉取请求工作流将翻译输出提交到拉取请求的来源分支。
拉取请求上的翻译命令将请求的翻译输出写入该拉取请求的来源分支。

通过拉取请求交付翻译时,来源分支必须位于已安装应用的仓库中,且可写入。应用会跳过派生仓库,并拒绝将此类输出直接写入默认分支。

应用会依次处理仓库任务,并过滤自身生成的提交,避免反复触发翻译。如果已配置的源文件没有变更,或目标内容已涵盖请求的翻译任务,运行可能完成但不产生差异。检查结果会说明具体情况;强制重新生成用于替换选定翻译,而不是让没有变更的运行看起来执行了操作。

在运行产生费用前要求批准 #

github.safety.requireApproval 默认为 false。如果翻译开始前必须有人授权此次运行,请在默认分支的配置中将其设为 true。默认分支推送触发的检查会显示批准和拒绝控件。对于拉取请求,应用会发表评论,由获授权的审核者使用 /lingo approve 回复。

如果要求批准,审计检查创建失败会阻止工作流继续执行。请先解决检查创建或访问问题,再尝试批准。

任何 /lingo translate 命令,无论是否包含文件通配模式,都会授权其请求的任务,并跳过这项预先批准。发布命令前,请检查文件和语言区域范围。

在拉取请求上运行命令 #

在尚未关闭的拉取请求上发表评论;其分支必须属于已安装应用的仓库,且不能是默认分支。应用会读取评论中第一个以 /lingo 开头的行。源语言区域、文件选项和目标语言区域取自拉取请求来源分支的配置,引擎和安全设置则取自默认分支。只有拥有仓库写入权限的人才能启动翻译。

命令作用
/lingo 或 /lingo help回复可用命令列表。
/lingo translate翻译此拉取请求中的源内容变更,并保留未变更的翻译。上次推送后仍在等待处理的翻译提案会被替换。
/lingo translate --locales fr,es仅为列出的语言区域翻译此拉取请求中的源内容变更。
/lingo translate <glob>...为匹配通配模式的已配置源文件创建缺失的目标文件。
/lingo translate <glob>... --force重新生成匹配的目标内容,替换现有翻译。--force 要求至少提供一个通配模式。
/lingo translate [<glob>...] --key <pattern>重新翻译现有翻译中匹配的命名键。
/lingo approve批准此拉取请求上等待处理的翻译提案。

未提供通配模式或 --key 时,命令会处理拉取请求中变更的文件,因此即使配置禁用了拉取请求处理,命令仍会运行。提供通配模式时,命令会处理分支上的文件,不受拉取请求变更范围的限制。通配模式相对于仓库根目录,区分大小写,且只能匹配已配置的 pattern 选中的文件。--locales 接受以逗号分隔的列表。语言区域代码与已配置目标语言区域的匹配不区分大小写;回复会指出未匹配任何目标语言区域的代码。

补全选定文件或语言区域和结合上下文重新翻译键详细介绍了通配模式和键命令的用法。

补全选定文件或语言区域 #

在拉取请求上发布限定范围的命令,请求处理一个已配置的文件和语言区域:

text
/lingo translate locales/en/checkout.json --locales fr

对于每个语言区域使用独立文件的格式,这会补全缺失的法语目标文件,但不会补全现有目标文件中缺失的键。添加 --force 会重新生成选定输出,不再复用现有目标内容,因此可能覆盖已接受的人工修改。请限定文件和语言区域的选择范围,再审核生成的差异。

Xcode 字符串目录和 CSV 文件将源内容与目标内容保存在同一个文件中。常规的限定范围命令会补齐缺失的语言区域条目,并保留现有条目,包括源内容已更改的条目。使用不带文件匹配模式的 /lingo translate,可翻译拉取请求中更改的源内容;这可能会替换相应条目的现有译文,包括人工编辑的内容。如果希望重新生成现有译文,请添加 --force,并将文件和语言区域的选择范围限定得更小。强制执行的应用命令会重建所选内容,同时保留请求范围之外的语言区域。通过 CLI 更新时,请遵循字符串目录或 CSV 的修正流程。

结合上下文重新翻译键 #

使用 --key 重新翻译现有翻译中选定的命名键。对于 JSON 和 JSONC 文件,可添加 --context 来说明这些键的含义,或为本次运行提供语气和大小写方面的指导:

text
/lingo translate --key "keyname" --context "button label, keep sentence case"

--context 必须配合 --key 使用。上下文只需提供一次,即可应用于 JSON 和 JSONC 文件中所有选定的键和语言区域。其他匹配格式的翻译不会使用该上下文。可重复使用 --key 来指定多个匹配模式,并用文件通配模式或 --locales 缩小请求范围。未提供文件通配模式时,命令会选取所有已配置的源文件。键支持精确匹配、前缀匹配或通配模式匹配;无关翻译会保留。不含命名键的格式,以及没有现有翻译的语言区域,会被跳过。

GitHub App 的键命令也会重新生成 YAML 和以语言区域为根节点的 YAML 中选定但未变更的字符串。对于这些格式,CLI 的键范围工作流采用不同的基准内容复用方式。

请将命令写在同一行。包含空格的上下文需用单引号或双引号括起;--context="button label" 也可使用。如果文本中需要包含与外围引号相同的引号,请用反斜杠转义,例如 --context "Use \"Save\" as a button label"。上下文会随运行保留,用于重试和历史记录,但不会保存为引擎指令,也不会被后续运行继承。现有术语表、占位符和输出格式规则仍然适用。

在用引号括起的上下文中,仅 \\ 和用于转义外围同类引号的反斜杠会被解码。$name 和 ${name} 等占位符、\n 等序列以及标点符号均按字面保留。

保护不应更改的内容 #

该应用支持结构化目录、Markdown 系列文档、HTML、字幕、纯文本、CSV 表格、Java 属性文件和平台资源。格式介绍了各类文件的处理程序。Payload 不在可选的 GitHub 文件格式之列。

使用 pages/en/**/*.html 和 pages/en/**/*.htm 等匹配模式选取 HTML 文件;这两种扩展名都会被推断为 html,也可显式指定 "format": "html"。HTML 输出会将翻译文本和选定属性更新到源内容中,保留未改动的标记、注释和格式。显式声明的 <html> 元素会在 lang 中写入目标语言区域;片段不会被额外包裹在文档结构中。

选择纯文本文件时,可使用以 .txt 结尾的匹配模式(例如 metadata/en/*.txt),也可使用 "format": "txt"。.txt 文件仅匹配这类条目,而使用 "format": "txt" 的条目仅匹配 .txt 文件。因此,像 docs/en/**/* 这样的宽泛匹配模式会跳过 LICENSE.txt,宽泛的 txt 条目则会跳过与文本放在一起的图片。纯文本会在原位置逐行翻译。

选择 CSV 文件的方式相同:使用以 .csv 结尾的匹配模式(例如 i18n/strings.csv),或使用 "format": "csv"。.csv 文件只能归入此类条目,而带有 "format": "csv" 的条目只会选取 .csv 文件。CSV 会填充源文件中的目标语言区域列。

选择 Java 属性文件时,方法相同:使用以 .properties 结尾的匹配模式(例如 src/main/resources/messages_en.properties),或使用 "format": "properties",让 src/main/resources/**/* 这类匹配范围较广的模式跳过 application.properties。名为 messages_en.properties 的源文件会生成 messages_de.properties 这样的目标文件。Java 属性会在原位翻译每个值,保留注释和排版,并沿用之前 CLI 的方式匹配 lockedKeys、preservedKeys、ignoredKeys 和 lockedPatterns。

对于文档,请选取包含可翻译文本的前置元数据字段和组件属性。对于 JSON 类文本目录,可用锁定路径复制源值,用保留路径保留现有目标值,用忽略路径将相应值排除在输出之外。这样,文本目录就能同时包含文本、标识符和链接,而无需让翻译器以同样的方式处理所有内容。语言区域注入会将目标语言区域写入配置的输出字段。

文件条目选项 #

请将以下字段直接放在 .lingo/config.json 的 files 数组中的对象内,而不是放在 options 下。应用会严格验证根字段、文件条目、GitHub 设置、组件规则和语言区域注入对象。可选的 i18n 部分会被忽略,该部分允许包含额外字段。机器可读的模式定义可在 GET https://api.lingo.dev/github-app/schema.json 获取。

字段接受的结构默认值或适用范围
pattern / include相对于仓库根目录的非空字符串 / 此类字符串组成的非空数组。至少提供一项;若提供 include,则优先于 pattern。匹配模式不能以 / 开头,也不能包含 ..。
exclude由相对于仓库根目录的非空匹配模式组成的数组。可选;仅适用于此条目。
format指定格式的字符串,包括 "html"。可选,未指定时自动推断;.html 和 .htm 选择 HTML。不能选择 Payload。这不是文档的 {type,options} 对象。
localeFormat"bcp47"、"underscore" 或 "android"。通常默认为 BCP-47;Android 格式采用 Android 写法。
targetPath, sourceRoot相对于仓库根目录的非空字符串。可选;须遵循上述输出模板规则。
lockedKeys, preservedKeys, ignoredKeys由采用点号或方括号表示法的非空键路径字符串组成的数组。省略时等同于 [];具体效果取决于格式处理器。这些不是文档原生的 JSONPath 选项。
injectLocale布尔值或 { "enabled": boolean, "key"?: nonempty string }。省略时禁用注入;启用后,若未提供 key,则默认为 language。
translateFrontmatterFields由非空字符串组成的数组。对于 Markdown 系列文档,省略时选择 title、description;[] 表示不选择任何内容。
translateComponentProps数组,元素可为非空属性名字符串,或包含可选 component 和必需的非空 props 数组的对象。component 为非空字符串,或由非空字符串组成的非空数组;省略时不按名称筛选。该字段默认为 []。

例如,JSON 条目可以在 pattern 之外添加 "lockedKeys": ["meta.id"], "preservedKeys": ["links.help"], "injectLocale": { "enabled": true, "key": "meta.locale" }。Markdoc 条目可通过 "translateComponentProps": [{ "component": "Callout", "props": ["title"] }] 选取组件标题。CLI 接受某些空值,对某些未知字段也仅发出警告,而应用会拒绝这些情况;请依据此模式定义验证应用配置。

检查并恢复首次周期性运行 #

通过 GitHub 检查和工作流运行,查明仓库、源修订版本、本地化引擎、选定文件、语言区域及交付分支。将这些信息与预期变更对照,再确定处理在哪个环节停止:

观察到的情况请求更多任务前应检查的内容
默认分支配置缺失、无效或禁用了工作流不会发布 GitHub 检查或评论。请修复并提交默认分支的 .lingo/config.json,确保包含预期的工作流设置。
默认分支检查通过后,源修订版本的配置缺失或无效运行会报告检查失败,并在适用的 PR 流程中发表评论。请修复报告中指出的源配置错误。
没有匹配的源内容变更,或所需翻译已齐全检查匹配模式和所选内容的翻译覆盖情况;没有需要执行的操作并不代表翻译失败。
此前遗漏的 PR 源内容变更PR 同步时,工作流可与 PR 基准版本比较,补回仅与紧邻的上一源版本比较时遗漏的任务。请一并检查基准版本、当前源内容和目标内容。
有人修改了 PR 的目标内容对于使用独立目标文件的格式,如果目标文件相较于基准版本有变更,且最新提交的作者不是机器人,常规 PR 增量处理会保护该目标文件。请检查这项修改,不要将跳过的输出视为遗漏的任务。
后续失败发生前已有部分提交输出可以分批提交。一次运行可能包含多个提交,后续批次失败不会回退先前成功的提交。请分别审核已交付的路径和剩余失败项。

输出会分组提交,每组最多 100 个文件,分组大小阈值为 5 MiB。后续失败可能不会撤销先前的提交。重试或回退此次运行前,请先审核已交付的路径和剩余失败项。

禁用相应触发器即可停止周期性任务。如果应用不应再拥有仓库操作权限,请在 GitHub 中撤销其仓库访问权限或卸载应用。现有提交、已接受的拉取请求和既有用量记录仍会保留;请按仓库的常规流程保留或回退已交付内容。

在 Radar 中收集活动 #

该连接还会向 Radar 提供 GitHub 提交活动。收集翻译用于测量介绍了事件设置,以及如何在运行历史测量前导入提供方历史记录。