Lingo.dev CLI 通过 bucket type 来解析和翻译不同的文件格式。每种 bucket type 都是专为特定格式打造的解析器。你可以在 i18n.json 中配置一个或多个 bucket，用来指定 CLI 需要翻译哪些文件。
Bucket 类型#
| Bucket 类型 | 格式 | 输出模式 | 是否需要 [locale] |
|---|---|---|---|
json | JSON 文件 | 按 locale 分别生成文件 | 是 |
json5 | JSON5 文件 | 按 locale 分别生成文件 | 是 |
jsonc | JSONC 文件（含注释） | 按 locale 分别生成文件 | 是 |
json-dictionary | JSON 字典（扁平键值对） | 按 locale 分别生成文件 | 是 |
yaml | YAML 文件 | 按 locale 分别生成文件 | 是 |
yaml-root-key | 以 locale 作为根键的 YAML | 直接修改源文件 | 否 |
markdown | Markdown 文件 | 按 locale 分别生成文件 | 是 |
mdx | MDX 文件 | 按 locale 分别生成文件 | 是 |
markdoc | Markdoc 文件 | 按 locale 分别生成文件 | 是 |
html | HTML 文件 | 按 locale 分别生成文件 | 是 |
mjml | MJML 邮件模板 | 按 locale 分别生成文件 | 是 |
android | Android XML 资源文件 | 按 locale 分别生成文件 | 是 |
xcode-strings | Xcode .strings 文件 | 按 locale 分别生成文件 | 是 |
xcode-stringsdict | Xcode .stringsdict 文件 | 按 locale 分别生成文件 | 是 |
xcode-xcstrings | Xcode .xcstrings 目录 | 直接修改源文件 | 否 |
flutter | Flutter ARB 文件 | 按 locale 分别生成文件 | 是 |
po | GNU gettext PO 文件 | 按 locale 分别生成文件 | 是 |
properties | Java .properties 文件 | 按 locale 分别生成文件 | 是 |
csv | CSV 文件 | 直接修改源文件 | 否 |
csv-per-locale | CSV 文件（每个 locale 一个文件） | 按 locale 分别生成文件 | 是 |
xml | 通用 XML 文件 | 按 locale 分别生成文件 | 是 |
xliff | XLIFF 文件 | 按 locale 分别生成文件 | 是 |
srt | SRT 字幕文件 | 按 locale 分别生成文件 | 是 |
vtt | VTT 字幕文件 | 按 locale 分别生成文件 | 是 |
php | PHP 本地化数组 | 按 locale 分别生成文件 | 是 |
typescript | TypeScript 文件 | 按 locale 分别生成文件 | 是 |
vue-json | Vue i18n JSON 区块 | 按 locale 分别生成文件 | 是 |
txt | 纯文本文件 | 按 locale 分别生成文件 | 是 |
输出模式#
Bucket 共有两种输出模式：
按 locale 分别生成文件 —— CLI 会为每种目标语言创建单独的文件。include 模式必须包含 [locale] 占位符：
json
{
"buckets": {
"json": {
"include": ["locales/[locale].json"]
}
}
}这会生成 locales/en.json、locales/es.json、locales/fr.json 等文件。
直接修改源文件 —— CLI 会将翻译结果写回包含源内容的同一个文件中，不使用 [locale] 占位符：
json
{
"buckets": {
"csv": {
"include": ["translations.csv"]
}
}
}CSV 文件通常会在同一个文件的不同列中存储所有 locale。Xcode .xcstrings 目录和以根键组织的 YAML 也是类似的方式。
配置示例#
使用 JSON 的 Web 应用#
json
{
"buckets": {
"json": {
"include": ["src/locales/[locale].json"],
"lockedKeys": ["brand/name"]
}
}
}使用 Markdown 的文档站点#
json
{
"buckets": {
"markdown": {
"include": ["docs/[locale]/*.md"],
"exclude": ["docs/[locale]/drafts/*.md"]
}
}
}移动应用（iOS + Android）#
json
{
"buckets": {
"xcode-xcstrings": {
"include": ["ios/Localizable.xcstrings"]
},
"android": {
"include": ["android/app/src/main/res/values-[locale]/strings.xml"]
}
}
}包含多种格式的 Monorepo#
json
{
"buckets": {
"json": {
"include": ["apps/web/locales/[locale].json"]
},
"mdx": {
"include": ["packages/docs/content/[locale]/*.mdx"]
},
"flutter": {
"include": ["apps/mobile/lib/l10n/app_[locale].arb"]
}
}
}Bucket 专属功能#
除了 include/exclude 模式外，部分 bucket 还支持以下附加功能：
| 功能 | 支持的 bucket | 说明 |
|---|---|---|
| Key Locking | 键值格式（JSON、YAML 等） | 直接复制源值，不进行翻译 |
| Key Ignoring | 键值格式 | 将这些键完全排除在目标文件之外 |
| Key Preserving | 键值格式 | 初始化一次，之后不再更新 |
| Translator Notes | JSONC、XCStrings | 通过注释提供上下文，提升翻译质量 |
Include 模式规则#
- 模式路径相对于
i18n.json文件所在位置 - 使用
[locale]作为 locale 代码的占位符（对“分别生成文件”类型的 bucket 为必填） - 星号（
*）可匹配任意文件名：locales/[locale]/*.json - 递归模式（
**）可匹配任意目录层级中的文件：src/**/[locale].json、config/locales/**/[locale].yml。当模式中使用**时，node_modules、.git、dist、build、.next和.turbo会默认被排除——如有需要，可额外添加自己的exclude条目（需 CLI 0.135.0+） - 文件扩展名不会影响解析方式——实际使用哪个解析器由 bucket type 决定
