Lingo CLI 全格式本地化实战基于 demo/new-cli 的 JSON、Markdown、MDX、Markdoc 与 OpenAPI 端到端翻译指南【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica这篇指南以 replexica 仓库中的 demo/new-cli 示例项目为核心系统讲解如何使用lingo.dev/cli将JSON、JSONC、Markdown、MDX、Markdoc 与 OpenAPI YAML六种文件格式一次性端到端翻译为多语言。读完本文你将掌握.lingo/config.json中injectLocale、lockedKeys、preservedKeys、translateFrontmatterFields、translateComponentProps与format等核心配置的用法并能在自己的仓库中复现完整的login → link → push → pull工作流。一、项目概览一个覆盖所有受支持格式的即用型 Demodemo/new-cli是一个开箱即跑的演示项目它展示的核心能力是用同一个 CLI 命令把每一种受支持的文件格式端到端翻译完毕。其目录结构如下demo/new-cli/ ├── .lingo/ │ ├── config.json # 每种格式一条 files[] 配置项附带格式专属选项 │ └── lock.json # CLI 生成的翻译锁定/状态文件 ├── content/ │ ├── en/ # 源语言Source Locale内容 │ │ ├── app.json # JSON — injectLocale lockedKeys │ │ ├── settings.jsonc # JSONC — preservedKeys注释得以保留 │ │ ├── guide.md # MD — translateFrontmatterFields │ │ ├── landing.mdx # MDX — translateComponentPropsHero、Callout │ │ ├── changelog.mdoc # Markdoc — frontmatter 与 tag 属性被保留 │ │ └── api.yaml # OpenAPI YAML — 显式 format: yaml-openapi │ ├── de/ # 德语目标语言示例翻译输出 │ ├── fr/ # 法语目标语言示例翻译输出 │ └── es/ # 西班牙语目标语言示例翻译输出 └── package.json # 一个私有privatenpm 包无运行时依赖源语言为en目标语言为de、fr、es仓库内直接提交了content/de/、content/fr/、content/es/三份已翻译的示例输出因此你不运行任何命令也能直接看到翻译结果使用你自己的 engine 重新运行 CLI 即可重新生成这些文件——CLI 会自动把en路径段替换为每个目标语言对应的路径段即 .lingo/config.json 中的injectLocale: true行为。二、获取 Demo 项目由于该目录位于 replexica 仓库内你可以直接在工作区查看其完整源码与示例输出也可以将其作为模板在自己仓库中重建相同结构。原文档推荐通过degit拉取模板的方式如下npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo cd my-lingo-demo注意命令中的lingodotdev/lingo.dev是上游模板仓库本文所有配置与源码分析均以当前 replexica 仓库内的 demo/new-cli 目录为准。三、运行环境与前置条件运行 Demo 需要以下条件一个 Lingo.dev 账号用于认证与翻译服务Node.js 环境——所有命令都通过npx执行无需全局安装任何 CLI 包已连接的组织org与引擎engine——push命令依赖link建立的连接。当前仓库根目录下的 i18n.json 与 i18n.lock 表明该仓库本身也采用同一套国际化工作流管理多语言内容这与 Demo 的使用方式是一致的。四、完整运行流程login → link → push → pull原文档给出的端到端命令序列如下# 1. 认证只需一次。 npx lingo.dev/clilatest login # 2. 将该项目连接到你的组织与引擎。 npx lingo.dev/clilatest link # 3.可选在翻译前预览成本。 npx lingo.dev/clilatest push --backfill-missing --estimate # 4. 把每个文件翻译成每个目标语言。 npx lingo.dev/clilatest push --backfill-missing # 5. 将翻译好的文件拉取回 content/locale/。 npx lingo.dev/clilatest pull4.1 login一次性认证login用于建立你的 Lingo.dev 身份凭证。它只需执行一次之后link、push、pull都会复用该凭证。4.2 link连接组织与引擎push需要已关联的组织与引擎因此必须先运行link。link会把当前项目与你在 Lingo.dev 平台上的特定 engine负责实际翻译任务的配置单元绑定。4.3 push --backfill-missing --estimate翻译前成本预览可选push支持--backfill-missing与--estimate两个关键标志--backfill-missing回填缺失内容——只翻译当前缺失的条目避免重复翻译已有内容、降低 token 消耗--estimate只估算不执行——在真正发起翻译前预览本次 push 的成本方便你在预算范围内决策。建议顺序是先带--estimate跑一次看成本确认无误后再正式push。4.4 push --backfill-missing正式翻译正式提交所有文件到你的 engine 进行翻译。CLI 会按照 .lingo/config.json 中每个files[]条目声明的格式与选项将content/en/下的每个文件翻译为de、fr、es三种语言。4.5 pull拉取翻译结果pull把翻译完成的文件写回到content/locale/对应目录。仓库中当前提交的content/de、content/fr、content/es文件就是示例输出你执行自己的push/pull后这些文件会被你的 engine 生成的翻译覆盖。五、配置核心.lingo/config.json 逐项拆解Demo 的灵魂在于 .lingo/config.json——它对每种格式声明一条files[]配置项。完整内容如下{ sourceLocale: en, targetLocales: [ de, fr, es ], files: [ { pattern: content/en/app.json, injectLocale: true, lockedKeys: [ meta.version ] }, { pattern: content/en/settings.jsonc, preservedKeys: [ featureFlags ] }, { pattern: content/en/guide.md, translateFrontmatterFields: [ title, description ] }, { pattern: content/en/landing.mdx, translateFrontmatterFields: [ title ], translateComponentProps: [ { component: [ Hero, Callout ], props: [ title, body ] } ] }, { pattern: content/en/changelog.mdoc, translateFrontmatterFields: [ title ] }, { pattern: content/en/api.yaml, format: yaml-openapi } ] }5.1 顶层sourceLocale 与 targetLocalessourceLocale: en声明源语言为英语targetLocales: [de, fr, es]声明三个目标语言德语、法语、西班牙语。5.2 pattern文件匹配规则pattern指定该条配置作用于哪个源文件如content/en/app.json。CLI 在pull时会据此把en路径段替换为目标语言路径段配合injectLocale。5.3 injectLocale是否注入语言路径段injectLocale: true意味着输出文件路径会自动插入目标语言段。例如源文件为content/en/app.jsonde目标的输出即为content/de/app.json——这正是 Demo 仓库目录结构的由来。对比仓库内 demo/new-cli 的content/de/、content/fr/、content/es/目录可以直观验证该行为。5.4 lockedKeys锁定键值不被翻译lockedKeys: [meta.version]表示app.json中meta.version这个键的值1.0.0永远保持原样。对照 content/en/app.json 与 content/de/app.json源文件version: 1.0.0德语输出version: 1.0.0——版本号被锁定未做任何改动。而nav、cta下的文案如home: Home→Startseite则全部完成翻译。5.5 preservedKeys整棵子树原样保留preservedKeys: [featureFlags]表示settings.jsonc中整个featureFlags子树逐字节保留。对照源码与德语输出源文件 settings.jsonc{ // User-facing labels are translated. labels: { theme: Theme, language: Language, notifications: Notifications }, // featureFlags are preserved verbatim (see preservedKeys in .lingo/config.json). featureFlags: { newOnboarding: true, betaEditor: false } }德语输出 content/de/settings.jsonc{ labels: { theme: Design, language: Sprache, notifications: Benachrichtigungen }, featureFlags: { newOnboarding: true, betaEditor: false } }两个关键观察labels下的用户可见文案被翻译Theme→DesignfeatureFlags子树newOnboarding: true、betaEditor: false原样保留——这正是preservedKeys的用途布尔开关、枚举值、技术标识符不应被本地化文件中的注释也得以保留这是 JSONC 格式相对 JSON 的核心价值详见第六节。5.6 translateFrontmatterFields指定要翻译的 frontmatter 字段Markdown 系格式MD、MDX、Markdoc的 frontmatter 中通常混合了需要翻译的文案与必须原样保留的技术字段因此需要显式声明guide.md声明title、description两个字段被翻译。对照 guide.md 与 content/de/guide.mdtitle: Getting started→title: Erste Schrittedescription: ...→ 德语描述slug: getting-started未被声明因此保持getting-started不变——slug 是 URL 技术标识符绝不能被翻译破坏链接结构landing.mdx与changelog.mdoc仅声明title被翻译其余 frontmatter 字段一律保持原样。5.7 translateComponentProps精确翻译 MDX 组件属性MDX 的复杂之处在于Markdown 与 JSX 混排组件属性props中既有文案也有代码。translateComponentProps采用白名单机制translateComponentProps: [ { component: [Hero, Callout], props: [title, body] } ]含义是只有Hero与Callout组件的title、body两个属性会被翻译其余一切 JSX 内容按代码处理。对照 landing.mdx 与 content/de/landing.mdx源文件中的Hero titleOne command to translate everything bodyPush your source files, pull them back in every language. /德语输出Hero titleEin Befehl, der alles übersetzt bodyÜbertrage deine Quelldateien und hole sie in jeder Sprache zurück. /组件名Hero、属性名title/body本身保持不变仅属性值被翻译正文 Markdown 段落同样被翻译。Callout组件中的说明文字也准确翻译了这条规则本身Component props listed in translateComponentProps are translated; everything else stays as code.——这正是该配置项的语义概括。5.8 format: yaml-openapi显式声明 OpenAPI 格式YAML 文件本身是通用的但 OpenAPI 规范有特殊的可翻译范围语义——只有人可读的字符串summary、description 等才应被翻译键名与标识符必须保留。因此 .lingo/config.json 对api.yaml显式声明{ pattern: content/en/api.yaml, format: yaml-openapi }对照 api.yaml 与德语输出可以看到summary: List all products、description: Returns a paginated list of products...等面向人的字符串被翻译openapi: 3.0.3、paths: /products、HTTP 状态码200/404、info.title等键名与标识符原样保留。六、六种格式的差异化处理策略下表汇总 Demo 中每种格式的配置要点与处理策略均可在 .lingo/config.json 与对应示例输出中验证文件格式关键配置核心行为app.jsonJSONinjectLocalelockedKeys语言路径段自动注入meta.version锁定不译settings.jsoncJSONCpreservedKeys注释保留featureFlags子树原样保留guide.mdMarkdowntranslateFrontmatterFields仅title/description翻译slug不动landing.mdxMDXtranslateFrontmatterFieldstranslateComponentProps仅白名单组件Hero/Callout的 title/body 属性被译changelog.mdocMarkdoctranslateFrontmatterFieldsfrontmatter 与{% callout %}标签属性被保留api.yamlOpenAPI YAMLformat: yaml-openapi只译人读字符串键名/标识符保留典型使用场景建议JSON应用文案配合lockedKeys锁定版本号、ID 等机器字段配合injectLocale自动生成content/locale/目录JSONC带注释的配置文件用preservedKeys保护featureFlags类布尔/枚举子树同时保留开发注释Markdown/MDX/Markdoc内容站点frontmatter 中的 URL slug、组件 props 中的代码性内容通过白名单精确控制避免破坏链接与组件逻辑OpenAPI YAMLAPI 文档声明yaml-openapi格式确保路径、响应码、字段名等结构化标识不受翻译影响。七、验证方式示例输出对照该 Demo 最实用的一点是仓库已内置三套完整的目标语言输出content/de、content/fr、content/es无需运行任何命令即可对照验证每种配置的效果查看de/app.json验证lockedKeys与injectLocale查看de/settings.jsonc验证preservedKeys与注释保留查看de/guide.md验证 frontmatter 中slug未变、正文与title/description已译查看de/landing.mdx验证 Hero/Callout 的 title/body 被译、其余 JSX 保持代码形态查看de/api.yaml验证 OpenAPI 键名保留、人读字符串被译。如需重新生成只需要完成login → link → push --backfill-missing → pull即可push/pull会用你 engine 的翻译覆盖这些示例文件。八、常见问题与注意事项必须先link再pushpush依赖已关联的组织与引擎跳过link会直接失败--estimate只是预览它不会产生实际翻译结果正式执行仍需去掉该标志的pushlockedKeys与preservedKeys的区别前者锁定单个键的值不翻译如meta.version后者保留整棵子树如featureFlags按需选择frontmatter 与组件属性默认不译需要翻译必须显式声明到translateFrontmatterFields/translateComponentProps白名单中这保证 URL slug、组件参数等代码性内容绝对安全OpenAPI 必须声明格式通用 YAML 无法自动识别 OpenAPI 语义务必使用format: yaml-openapi示例输出会被覆盖content/de、content/fr、content/es是提交在仓库中的样例执行push/pull后将被你的引擎结果替换。九、延伸阅读配置文件的完整定义可参考 packages/spec/src/config.ts 及其测试 packages/spec/src/config.spec.ts从中可以确认sourceLocale、targetLocales、files[].pattern、injectLocale、lockedKeys、preservedKeys、translateFrontmatterFields、translateComponentProps等字段的 schema 定义各格式加载器loader与格式化器的实现位于 packages/cli/src/loaders其中json-dictionary、flat、markdown、mdx、yaml等目录与 Demo 中的格式一一对应想了解 CLI 命令login、link、push、pull的更多细节可查看 packages/cli/src/cli/cmd 目录下的命令实现与 packages/cli/README.md。通过这个 Demo你可以用最小的成本验证 Lingo CLI 对主流内容格式的完整支持链路并以此为模板把同样的.lingo/config.json结构复制到自己的产品仓库中实现一套配置、全格式、多语言的本地化工程化落地。【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考