Lingo.dev CLI 可通过已配置的 本地化引擎 翻译仓库中的静态文件——包括 Markdown、MDX、Markdoc、JSON、YAML、字幕等。只需指向你的内容，运行一次，即可在源文件旁生成对应的译文文件。
支持的内容类型#
| 内容类型 | 格式 | CLI bucket | 示例路径 |
|---|---|---|---|
| 文档 | Markdown | markdown | docs/[locale]/getting-started.md |
| 文档 | MDX | mdx | docs/[locale]/getting-started.mdx |
| 文档 | Markdoc | markdoc | docs/[locale]/getting-started.mdoc |
| 结构化数据 | JSON | json | data/[locale].json |
| 结构化数据 | YAML | yaml | data/[locale].yaml |
| 博客文章 | Markdown / MDX | markdown / mdx | blog/[locale]/post-slug.md |
| 字幕 | SRT | srt | subs/[locale]/intro.srt |
| 字幕 | VTT | vtt | subs/[locale]/intro.vtt |
| 电子表格 | CSV | csv-per-locale | data/[locale].csv |
| 配置字符串 | Properties | properties | lang/[locale].properties |
| 配置字符串 | Gettext PO | po | locale/[locale]/messages.po |
| 纯文本 | TXT | txt | content/[locale]/readme.txt |
前置条件#
每次运行 CLI，内容都会经过一个 本地化引擎——也就是决定使用哪种 LLM 模型、术语表、品牌语调和指令的配置。你可以在 Lingo.dev 控制台中创建引擎，并生成 API 密钥。
文档站点#
大多数文档框架都会按语言区域目录组织翻译内容。CLI 的 markdown、mdx 和 markdoc buckets 可在保留 frontmatter、代码块和组件语法的同时翻译这些文件。
json
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"markdown": {
"include": ["docs/[locale]/getting-started.md"]
},
"mdx": {
"include": ["docs/[locale]/setup.mdx"]
}
}
}调整 include 模式，以匹配你所用框架的目录约定：
| 框架 | 语言区域目录约定 | 参考资料 |
|---|---|---|
| Docusaurus | i18n/[locale]/docusaurus-plugin-content-docs/current/ | Docusaurus i18n 指南 |
| Nextra | 按语言区域拆分的页面或 JSON 字典 | Nextra 文档 |
| Hugo | content/[locale]/ | Hugo 多语言指南 |
| Astro | src/content/[locale]/ 或 JSON 字典 | Astro i18n 指南 |
| VitePress | [locale]/ 目录前缀 | VitePress i18n |
| MkDocs | 配合 i18n 插件使用按语言区域划分的 docs/ | MkDocs i18n 插件 |
MDX 组件
mdx bucket 会在翻译过程中保留 JSX 组件语法。像 <Callout>、<Tabs> 和 <CodeBlock> 这样的自定义组件都会原样保留——只有其中的文本内容会被翻译。
结构化数据#
JSON 和 YAML 文件可通过 json 和 yaml buckets 翻译。使用 锁定键 可防止不可翻译的值（如 ID、URL、配置标志）被改动。
json
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"json": {
"include": ["content/[locale].json"],
"lockedKeys": ["id", "slug", "url"]
},
"yaml": {
"include": ["data/[locale].yaml"]
}
}
}对于以语言区域代码作为根键的 YAML 文件（常见于 Rails 和 Hugo），请改用 yaml-root-key bucket——它会从源语言区域键读取内容，并在同一文件中写入目标语言区域键。
字幕#
SRT 和 VTT 字幕文件可通过 srt 和 vtt buckets 翻译。CLI 会保留所有时间数据、字幕序号和格式标签——只翻译文本内容。
json
{
"$schema": "https://lingo.dev/schema/i18n.json",
"version": "1.15",
"locale": {
"source": "en",
"targets": ["es", "fr", "de", "ja"]
},
"buckets": {
"srt": {
"include": ["subs/[locale]/intro.srt"]
}
}
}处理大型内容#
静态内容仓库中可能包含数千个文件。CLI 通过以下三种机制高效处理：
| 机制 | 作用 |
|---|---|
| Lockfile | 跟踪源内容的 SHA-256 指纹。后续运行时，只有新增或修改过的文件才会触发翻译。 |
| 并行处理 | 将翻译任务分配给并发工作进程。可通过 run --concurrency 20 进行配置。 |
| 定向运行 | 仅处理特定 bucket 或语言区域：run --bucket markdown 或 run --target-locale es。 |
