从源码生成参考文档：Lingo.dev 的 CLI 与 i18n.json 配置文档自动生成脚本解析-北京尧图网络

从源码生成参考文档Lingo.dev 的 CLI 与 i18n.json 配置文档自动生成脚本解析【免费下载链接】replexicaOpen-source localization engineering tools. Connects to Lingo.dev localization engineering platform for consistent, quality translations.项目地址: https://gitcode.com/GitHub_Trending/re/replexica本篇技术指南聚焦 Lingo.dev本仓库核心项目CLI 名为lingo.dev的scripts/docs文档自动化体系系统讲解如何通过两个生成器脚本从 CLI 的 commander 程序定义与i18n.json的 Zod Schema 自动产出结构化参考文档。读完本文你将掌握这两个脚本的调用方式、输出形态、底层实现原理含 mdast 语法树渲染、JSON Schema 转换、PR 评论集成并能结合源码自行扩展文档生成链路。一、scripts/docs文档即代码的自动化入口在 Lingo.dev 这样的开源本地化工程工具中CLI 命令数量众多、i18n.json配置项持续演进人工维护参考文档既易遗漏又难保与源码一致。scripts/docs目录正是为解决这一痛点而存在的文档生成器工作区它从源代码而非手写文案提取事实保证文档与实现永不脱节。该目录scripts/docs包含两个可独立运行的生成器脚本生成对象输出形式generate-cli-docsLingo.dev CLI 参考文档每个顶层命令一个.mdx文件 index.mdx聚合页generate-config-docsi18n.json配置属性参考文档单个 Markdown 文件两者的入口定义见 scripts/docs/package.json均通过tsx直接运行 TypeScript 源码并复用同一个lingo.dev/_specworkspace 包、unified/remark-stringify渲染栈、prettier格式化与octokit/restGitHub 集成。二、generate-cli-docs为 CLI 生成结构化参考文档2.1 用法pnpm --filter docs run generate-cli-docs [output_directory]output_directory为必填参数脚本会创建该目录递归创建并为每个顶层命令写入一个command.mdx文件同时写入一个聚合所有命令的index.mdx。具体实现在 scripts/docs/src/generate-cli-docs.ts 的main()中outputDir通过resolve(process.cwd(), outputArg)解析后mkdir(outputDir, { recursive: true })确保目录存在。2.2 工作原理三步走原文档归纳的三步流程在源码中可逐一对号入座加载 CLI 程序getProgram()从仓库根目录解析出 packages/cli/src/cli/index.ts通过import(pathToFileURL(filePath).href)动态导入其默认导出——一个InteractiveCommand基于 commander实例。该文件集中注册了init、i18n、auth、login、logout、show、config、lockfile、cleanup、ci、status、run、purge等顶层命令还通过-y, --no-interactive提供脚本化所需的非交互模式这些事实都会反映到生成的文档中。遍历命令树buildCommandSection()递归处理顶层命令与子命令。关键过滤逻辑包括isHiddenCommand()跳过_hidden标记如may-the-fourth彩蛋命令、isHelpCommand()剔除自动生成的 help 命令、sub.parent command仅保留直属子命令。生成结构化.mdx每篇文档先构建 YAML frontmattertitle为完整命令路径subtitle为 CLI reference docs forcommand再由toMarkdown()将 mdast 根节点通过remark-stringify序列化为 Markdown最后用formatWithPrettier()依据仓库的 prettier 配置统一排版。2.3 生成文档的章节骨架每个命令的参考文档包含如下结构化小节由buildCommandSection与buildArgumentListItems/buildOptionEntries产出Usagecommand.createHelp().commandUsage(command)生成的标准用法行Aliasescommand.aliases()列出的所有别名Arguments格式化后的位置参数如必填参数渲染为name、可选为[name]、可变参数追加...并附描述、默认值、可选值choices与是否必填Options / Flags通过partitionOptions()将可见选项拆分为取值选项required/optional与布尔标志两类每个选项单独生成一个### signature小节包含用法示例、描述与细节是否必须指定、是否要求值、默认值、允许值、关联环境变量、预设值等Subcommands递归嵌套子命令的完整章节层级深度通过Math.min(depth 1, 6)收敛在 H6 以内。从源码可见buildOptionDetails()会读取 commanderOption的mandatory、required、optional、defaultValueDescription、defaultValue、argChoices、envVar、presetArg等元数据这意味着只要命令定义写得规范文档就能自动携带默认值、枚举取值与环境变量信息无需二次手写。2.4 双模式输出本地文件 vs GitHub Action PR 评论脚本依据process.env.GITHUB_ACTIONS决定输出方式这也是原文档 Notes 节的源码级解释非 CI 环境为每个顶层命令写入slugifyCommandName(command.name()) .mdx文件slug 化规则见slugifyCommandName()并额外生成index.mdx——该聚合页 frontmatter 带seo: noindex: true标题为rootName CLI referenceGitHub Action 环境不再写文件而是将所有命令文档拼接后通过 scripts/docs/src/utils.ts 的createOrUpdateGitHubComment()发布到 PR。它以固定标记!-- generate-cli-docs --定位已有评论先issues.listComments查找以该标记开头的评论存在则updateComment更新否则createComment新建实现幂等刷新避免每个 PR 堆积重复评论。评论正文会提示贡献者你的 PR 改变了 CLI 行为请审阅重新生成的参考文档。该流程依赖的GITHUB_TOKEN、GITHUB_REPOSITORY格式owner/repo、PR 号PR_NUMBER或解析GITHUB_EVENT_PATH中的pull_request.number均有对应工具函数getGitHubToken()、getGitHubRepo()、getGitHubOwner()、getGitHubPRNumber()负责读取缺失即抛错相关边界行为由 scripts/docs/src/utils.test.ts 覆盖。三、generate-config-docs为 i18n.json 生成配置属性参考文档3.1 用法pnpm --filter docs run generate-config-docs [output_file_path]在本地执行时output_file_path为必填参数脚本将生成的 Markdown 参考文档写入该路径自动创建父目录在 GitHub Action 环境下则把文档以details折叠块形式贴到 PR 评论中标记!-- generate-config-docs --。3.2 工作原理三步走实现在 scripts/docs/src/generate-config-docs.ts 的main()Zod Schema → JSON Schema从lingo.dev/_spec的 packages/spec/src/config.ts 导入LATEST_CONFIG_DEFINITION当前为configV1_15Definition调用zodToJsonSchema(schema, { name: I18nConfig, markdownDescription: true })完成转换markdownDescription: true会把 Zod 的.describe()文本写入 JSON Schema 的markdownDescription字段供渲染阶段优先读取。遍历全部属性parseSchema()见 scripts/docs/src/json-schema/parser.ts先沿$ref定位根定义#/definitions/I18nConfig再按ROOT_PROPERTY_ORDER [$schema, version, locale, buckets]优先排序顶层键其余键按必填优先、字母序排列随后递归展开每个属性收集类型、必填性、默认值、允许值enum、允许键propertyNames.enum以及嵌套子属性。值得留意的是generateMarkdown()会显式将version属性的默认值覆盖为LATEST_CONFIG_DEFINITION.defaultValue.version确保文档中的版本号始终跟随最新 schema。渲染完整 MarkdownrenderMarkdown()见 scripts/docs/src/json-schema/markdown-renderer.ts将解析结果转为 mdast 节点每个属性生成一个## fullPath标题嵌套层级按点号数量递增深度封顶 H6正文段落来自描述随后是固定列表项——Type: ...、Required: yes/no以及按需出现的Default:、Allowed values:、Allowed keys:数组元素的对象属性以fullPath.*形式递归展开。最终由remark-stringify序列化并追加标题为 i18n.json properties 的 YAML frontmatter。3.3 文档背后的配置模型生成器产出的参考文档本质上是对 packages/spec/src/config.ts 中分层 schema 的完整物化。从源码可梳理出i18n.json的顶层结构$schema默认https://lingo.dev/schema/i18n.jsonv1.4 引入versionschema 版本号从数字 0 逐步演进到字符串1.15configV0Definition→configV1_15Definition的每个版本都通过extendConfigDefinition在旧版之上扩展字段并提供createUpgrader完成旧配置的迁移例如 v1.1 把{glob: type}形式的 buckets 重写为{type: {include: [...]}}v1.15 将已废弃的vNext自动迁移为engineIdlocalesource源语言码支持en、en-US、pt_BR、pt-rBR等写法、targets目标语言码数组v1.2 起可选extraSource作为翻译回退源bucketsbucketTypeSchema见 packages/spec/src/formats.ts枚举了ail、android、csv、ejs、flutter、html、json、json5、jsonc、markdown、markdoc、mdx、mjml、twig、xcode-strings、xcode-stringsdict、xcode-xcstrings、yaml、yaml-root-key、properties、po、xliff、xml、srt、vtt、php、typescript、vue-json、json-dictionary、csv-per-locale等三十余种 bucket 类型每个 bucket 值对象支持include/exclude字符串路径或{path, delimiter}对象支持**递归匹配、keyColumnCSV 专用行标识列、injectLocale、lockedKeys、lockedPatterns、ignoredKeys、preservedKeys、localizableKeys等翻译行为控制项provider机器翻译提供商配置id枚举openai、anthropic、google、ollama、openrouter、mistral配合model、prompt、可选baseUrl与settings.temperature0~2部分模型如 GPT-5 要求 1formatter全局代码格式化器可选prettier或biome未指定且检测到 prettier 配置时默认使用 prettierv1.9 引入dev开发期设置目前支持usePseudotranslator布尔项用于在不调用真实翻译 API 的情况下用伪翻译器测试 i18nv1.14 引入engineIdLingo.dev 引擎标识v1.15 引入替代vNext。这套 schema 正是 i18n.json 与仓库各包如 packages/cli/i18n.json实际配置的校验依据生成器文档与运行时解析共用同一份事实来源保证一致性。四、共享基础设施与质量保障两个生成器共享 scripts/docs/src/utils.ts 提供的工具函数getRepoRoot()从当前模块位置逐级向上查找.git目录定位仓库根供加载 CLI 源码与解析 prettier 配置使用createOrUpdateGitHubComment()基于 Octokit 的幂等评论写入见上文 2.4formatMarkdown()读取仓库根 prettier 配置后以parser: markdown格式化生成的文档。测试方面目录内配有 scripts/docs/src/utils.test.ts、scripts/docs/src/json-schema/parser.test.ts 与 scripts/docs/src/json-schema/markdown-renderer.test.ts通过pnpm --filter docs testvitest验证工具函数、schema 解析与渲染逻辑为文档生成的正确性兜底。五、环境前提与运行注意事项仓库使用 pnpm workspace见 pnpm-workspace.yaml运行前需确保依赖已安装docs包依赖lingo.dev/_specworkspace 包、zod、zod-to-json-schema、commander、unified、remark-stringify、prettier、tsx与octokit/rest等本地运行generate-cli-docs必须提供输出目录参数generate-config-docs必须提供输出文件路径参数否则脚本直接抛错在 GitHub Action 中运行时须注入GITHUB_TOKEN、GITHUB_REPOSITORY并提供 PR 号PR_NUMBER或GITHUB_EVENT_PATH否则评论集成会失败生成的.mdx文件头部 frontmattertitle/subtitle/seo是为文档站预留的元数据可直接被静态站点生成器消费。六、总结scripts/docs提供了一条源码 → 结构化参考文档的自动化链路generate-cli-docs从 packages/cli/src/cli/index.ts 的 commander 命令树出发借助 mdast/remark-stringify/prettier 为每个命令产出带完整参数与子命令信息的.mdx并支持在 PR 上幂等评论generate-config-docs则把 packages/spec/src/config.ts 的 Zod schema 转为 JSON Schema再渲染成覆盖$schema、version、locale、buckets、provider、formatter、dev、engineId及全部 bucket 控制项的i18n.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），仅供参考

从源码生成参考文档：Lingo.dev 的 CLI 与 i18n.json 配置文档自动生成脚本解析

相关推荐

Ollama 部署 DeepSeek R1：本地知识库与 API 实践

RealSense点云生成完整流程

Roc 编译器 App Header 快照测试解析：以 roc 版本固定（app_header__roc_version）为例

更多资讯

WorkBuddy深度拆解：AI工作台的产品化、生态与规模工程

AWS SDK for Java v2 事件流备用语法设计解析：Running{Operation} 异步 API 提案

Storybook MDX 文档专用页（Documentation-only Page）完整实战指南：用 Meta Doc Block 构建独立文档与组件文档

Claude Code生态审计：Skill安全与资源库治理

WNDCLASS 光标加载教程，这次用 TaoToken 让 Codex 走通 hCursor 设置

VS Code 远程代码同步：SFTP、Remote-SSH、rsync 三种方案

今日更新

AReaL 调试指南：从 Agent Workflow 验证到分布式训练死锁诊断

MATLAB实现GPS L1 C/A信号仿真与二维捕获验证

彻底搞懂ASCII、Unicode与UTF-8：从乱码根源到编码实战

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？