CLI 配置

在 .lingo/config.json 中设置源文件发现规则、翻译选项和目标路径。

.lingo/config.json 指定项目需要翻译的文件,以及目标文件的存放位置。CLI 从工作目录向上查找最近的配置,并以该配置所在目录为根目录,解析项目相对路径。没有配置时,本地翻译目录命令使用当前工作目录。

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

运行 link,添加远程翻译所需的组织 ID 和本地化引擎 ID。即使没有这些 ID,提取操作也能在本地使用 i18n 设置。请使用严格的 JSON 格式:此处不支持注释和尾随逗号。

根级字段 #

字段含义
orgId, engineId非空资源 ID;两者共同构成远程绑定。
sourceLocale非空的源语言区域字符串。
targetLocales非空字符串条目;运行时会移除重复项,以及与源语言区域完全相同的条目。
files下文介绍的源文件条目。
i18n.messagesPath提取、检查和清理操作使用的翻译目录;默认为 locales。
i18n.typesPath提取和检查操作使用的声明文件路径;默认为 lingo.d.ts。
github.workflows.onPushToDefaultBranch.enabled可选的默认分支集成触发器。
github.workflows.onPullRequest.enabled可选的拉取请求集成触发器。
github.safety.requireApproval可选的集成运行审批设置。

未知的根级键和文件条目键会触发警告,并被忽略。因此,拼写错误可能让默认值继续生效,而不会导致整个文件被拒绝。

init 写入本地化设置;link 写入绑定 ID;unlink 只移除这些 ID。写入操作会保留其他根级部分,但 init --force 会重建文件条目,导致高级选项丢失。GitHub 设置既不会安装应用,也不会让 CLI 推送触发仓库自动化;请使用集成设置。

文件条目字段 #

字段含义
pattern一个非空的源文件匹配模式。
include源文件匹配模式;即使为空,也优先于 pattern。
exclude此条目要排除的匹配模式。
format从下方支持的格式列表中显式指定的格式。
localeFormatbcp47、underscore 或 android 路径表示方式。
targetPath, sourceRoot输出模板,以及生成 [path] 时要移除的可选前缀。
translateFrontmatterFields由 Markdown 系列处理器选取的元数据字段。
translateComponentProps属性名,或按组件筛选的属性规则。
lockedKeys, preservedKeys, ignoredKeys供支持此功能的处理器使用的非空键路径数组。
injectLocale布尔值或 { "enabled": true, "key": "language" }。
keyColumn仅适用于 CSV:键列的表头;默认为第一个表头单元格。
lockedPatterns仅适用于属性文件:值中的 RE2 正则表达式保留原样,不作翻译。

每个条目都必须提供 pattern 或 include;空的 include 不会选取任何内容。选项由第一个匹配的条目提供。键控制介绍了值的归属和格式边界。

文件匹配模式 #

匹配器支持在路径段内使用 *,也支持用 **/ 跨目录匹配。匹配递归子树时,请使用 docs/en/**/*;仅在末尾添加 ** 并不具有相同含义。不要假定它的大括号或扩展通配符行为与其他通配符库相同。

json
{
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "files": [
    {
      "include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
      "exclude": ["docs/en/private/**/*"]
    }
  ]
}

排除规则只对其所在条目生效;其他条目仍可包含该文件。文件发现会跳过 .git 和 node_modules,但不会跳过 .gitignore 中的所有内容。推送命令中作为位置参数传入的匹配模式,会进一步与已配置的源文件取交集,并改变规划模式。在命令行中,请用引号包裹这些模式。

格式选择 #

已配置的格式包括 json、jsonc、md、mdx、markdoc、yaml-openapi、po、flutter、xcode-strings、yaml、android、typescript、xcode-xcstrings、srt、xliff、xcode-stringsdict、php、yaml-root-key、html、txt、csv 和 properties。

后缀推断格式
.json、.jsoncJSON 或 JSONC。
.md、.mdx、.mdocMarkdown、MDX、Markdoc。
.html、.htmHTML。
.po、.arbGettext、Flutter。
.strings、.xcstrings、.stringsdict对应的 Apple 格式。
.ts、.mts、.ctsTypeScript。
.srt, .xlf, .xliff, .phpSubRip、XLIFF、PHP。
.txt纯文本,仅适用于以 .txt 结尾的匹配模式,或指定 txt 格式的情况。
.csvCSV,仅适用于以 .csv 结尾的匹配模式,或指定 csv 格式的情况。
.propertiesJava 属性文件,仅适用于以 .properties 或 properties 格式结尾的匹配模式。
.yaml、.yml请显式设置 yaml、yaml-root-key 或基于 yaml 的 OpenAPI。
.xml请显式设置 android;不支持通用 XML。

OpenAPI 的确切标识符为 yaml-openapi。即使显式指定格式,也仍受文件发现机制支持的后缀列表限制。.txt、.csv 或 .properties 文件只能归入匹配模式以相应扩展名结尾,或指定了对应格式(txt、csv 或 properties)的条目;这类条目也只会选择具有相应扩展名的文件。.js、.tsx、.pot、MJML 和 VTT 文件不属于已配置的 CLI 文件输入。React TSX 提取则是另一项操作。

HTML 翻译会将选定文本和属性的译文写回原始源码,保留未改动的标记、注释和格式。如果源码中有显式的 <html> 元素,其 lang 属性会设为目标语言区域;片段仍保持为片段。有关文本选择和输出行为,请参阅 HTML。

格式介绍了解析器的行为,包括会跳过的结构和重建限制。共享的服务端处理器不会扩展此 CLI 枚举。

输出路径 #

如果源文件路径无法标识其语言区域,请使用显式模板:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    {
      "pattern": "docs/**/*.md",
      "sourceRoot": "docs",
      "targetPath": "i18n/[locale]/docs/[path]"
    }
  ]
}

docs/start.md 会变为 i18n/de/docs/start.md 和 i18n/fr/docs/start.md。[locale] 使用该条目的语言区域表示方式;[path] 按路径段边界移除源根目录。以 docs 为根目录时,不会移除 docsite 的一部分。

模板必须包含 [locale];通配符输入还必须包含 [path]。仅支持这两个占位符。绝对路径、..、通配符根目录、输入范围之外的根目录,以及会被重新发现为已配置源文件的输出,都会被拒绝。没有 targetPath 的 sourceRoot 无效。推送还会检查不区分大小写的输出路径冲突。

推送、拉取和清除也会检查文件系统中的实际路径:如果源文件、目标文件、.lingo/lock.json 或 .lingo/config.json 解析到项目根目录之外或 .git 内部,例如通过符号链接,命令会在对该位置进行任何读取、写入或删除之前报错并停止。指向项目内部的链接仍可使用,但如果目标文件或 Lockfile 本身是链接,则不会通过该链接写入。在单仓库项目中,请从包含共享文件的根目录运行,而不是从某个包中链接到这些文件。

没有模板时,路径推导会依次尝试源语言区域目录、完整文件名主干、平台布局,最后插入语言区域目录并发出警告。例如 locales/en.json → locales/de.json、app_en.arb → app_de.arb、Base.lproj → 目标 .lproj,以及 Android values → 带语言区域限定符的资源。请留意警告,并确认应用会加载该目标位置。

XCStrings 和 CSV 将所有语言区域存储在源文件中,并拒绝 targetPath。多个语言区域的输出会有意共用该文件;文件存在并不代表其中包含每个语言区域。清除会跳过共享文件,因此无法移除单个语言区域条目。

选择元数据和组件文本 #

省略该选项时,Markdown 系列翻译会选取前置元数据中的 title 和 description。空列表表示不选取;显式列表则可选取其他字段。嵌套标量和数组路径要求前置元数据可被解析;如果前置元数据格式有误,可能会回退到顶层扫描。

json
{
  "pattern": "docs/en/**/*.mdx",
  "translateFrontmatterFields": ["title", "description"],
  "translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}

字符串会选取某个属性,不按组件筛选。对象会选取 props,并可限定组件名称。这些规则只选取可翻译的字面量内容,而不是组件代码或所有属性。Markdown、MDX 和 Markdoc 的处理方式不同;切换路径时,请检查对应处理器。

为 JSONC 提供翻译指导时,请将 @context 放在对应字符串的紧前方。常规 JSONC 输出会保留 @orphan 标记,但会删除其他注释。因此,React 的 @src 元数据需要遵循翻译目录加载策略,不能假定拉取操作会保留这些元数据。

使用文档框架时,请将实际源目录和输出目录的选择与路由分开处理。OpenAPI 使用 yaml-openapi;Rails 风格的语言区域根节点使用 yaml-root-key;通用 YAML 使用 yaml。仅凭扩展名匹配,无法选择正确的语义。

语言区域 #

配置只验证字符串是否非空,不会依据完整的语言区域枚举进行验证。请使用模型和应用所需的标识符,包括地区或文字体系。localeFormat 控制路径:bcp47 保留连字符,underscore 生成 pt_BR,android 生成 pt-rBR 或 b+zh+Hans 等形式。除非另行覆盖,Android 格式会采用 Android 的表示方式;这也会影响源文件匹配。

请先完成待处理的常规源文件更新,再添加目标语言区域并补齐其缺失文件。添加语言说明了这一顺序如何让现有语言保持最新。移除目标语言区域会停止后续选取,但不会删除现有文件。嵌入式语言区域元数据和共享翻译目录需要遵循对应处理器的规则。路径拼写正确,并不意味着文字方向、路由和语言质量也正确。

翻译目录路径 #

提取和检查操作按以下优先级取值:显式的 --out/--types、i18n 设置、默认值。--source-locale 默认为 en,不受本地化 sourceLocale 影响。更改 messagesPath 不会更新 files[];请选取生成的 JSONC 路径进行翻译。

单仓库项目 #

根配置可让递归匹配或显式指定的包路径共享语言区域和本地化引擎。也可以为每个包单独配置,让各包的语言区域、配置和 Lockfile 保持独立。请从预期的包根目录运行,避免向上查找最近配置时意外选中上级目录中的配置。

CI 目录矩阵应保留每个项目收集的输出,并避免写入操作相互重叠。主目录中的本地运行指针依赖绝对根路径,不会通过 Lockfile 共享。lingo check 会在文件层面,将 files 选取的每个源文件与 Lockfile 进行比较;不会检查文件内部的键。

评分配置 #

lingo score 使用可执行的 lingo.config.ts,并通过 Jiti 加载。它独立于项目 JSON,也不会注册任意本地格式加载器。请将可信的评分插件与远程文件本地化设置分开管理。