CLI v0 配置

配置旧版文件分组、语言区域路径和翻译后端,避免混用不同代际的配置。

lingo.dev@0.138.10 从工作目录读取 i18n.json。文件分组指定解析器并查找文件;语言区域设置指定源语言区域和目标语言区域。这套配置约定与当前的 .lingo/config.json 相互独立。

声明语言区域和文件分组 #

json
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": { "source": "en", "targets": ["es", "fr"] },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name"],
      "ignoredKeys": ["internal/*"],
      "preservedKeys": ["legal/terms"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

路径以配置文件所在位置为基准解析。使用哪个解析器由文件分组的键决定,而非文件扩展名。如果某种格式在一个文件中存储多个语言区域,请查阅旧版格式/输出对照表。

version 字段记录配置架构的代际版本。迁移旧版配置架构可以更新该文件,但不必迁移到当前 CLI。请保留原有配置,并逐一检查生成的更改。

有针对性地匹配路径 #

[locale] 会展开为源语言区域或目标语言区域代码。为路径单独设置分隔符,即可支持含下划线的文件名:

json
{
  "include": [
    "standard/[locale].json",
    { "path": "legacy/[locale].json", "delimiter": "_" }
  ]
}

对于 en-US,第二条路径使用 legacy/en_US.json。文件名中的表示方式与发送到后端的规范化语言区域值相互独立。

从 0.135.0 起支持递归查找 **;更早的版本需要显式指定路径。递归查找默认排除 node_modules、.git、dist、build、.next 和 .turbo。其他自动生成的目录树也需添加排除规则。

设置键的行为 #

旧版键控制使用斜杠分隔的遍历路径和通配符匹配。modules/ai.translation 选择 modules 中包含点号的字面键。锁定会复制源值,忽略会省略输出,保留则会先用源值填补缺失值,再交由人工维护。injectLocale 根据目标语言区域代码选择输出键。

有关具体效果,请参阅键控制。翻译指令不能保护结构,源语言占位文本也仍需经过人工翻译才能使用。

选择本地化引擎或直接使用提供商 #

使用 Lingo.dev 凭据时,engineId 会选择本地化引擎的术语表、规则、品牌语调和模型。建议明确指定。省略此项会由后端策略决定,而不是指定一套稳定的配置;当前服务可能要求提供 ID,也可能选择该密钥可访问的最早的已启用本地化引擎。

直接使用提供商时,需指定提供商 ID、模型和提示词。以下是历史配置形式,并不意味着其中指定的模型如今仍然可用:

json
{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

提示词会将 {source} 和 {target} 替换为语言区域代码。不要依赖 provider.baseUrl 来重定向 lingo.dev@0.138.10 的 run 请求。其 OpenAI 实现传入 baseUrl,而锁定版本的提供商依赖读取的是 baseURL,因此该配置值会被忽略。该依赖支持的是 OPENAI_BASE_URL;发送内容或凭据前,请确认目标地址符合预期。Ollama 实现同样忽略 provider.baseUrl,并使用默认设置创建提供商。运行器必须能够访问其服务;远程运行器无法使用笔记本电脑的本机回环地址。

后端凭据
Lingo.devLINGO_API_KEY
OpenAIOPENAI_API_KEY
AnthropicANTHROPIC_API_KEY
GoogleGOOGLE_API_KEY
MistralMISTRAL_API_KEY
OpenRouterOPENROUTER_API_KEY
本地 Ollama本地配置不使用提供商 API 密钥。

LINGO_API_URL 会更改 Lingo.dev 服务的目标地址;仍需检查兼容性和可信度。不要将凭据写入配置或日志。更改后端或文件查找设置后,请复现一次小规模的首个文件运行。更改模型或提示词不会改变源内容指纹,因此若要更新现有文本,就需要主动刷新。