FreeLLMAPI 多语言文档体系翻译工作流、目录镜像约定与术语一致性实战指南【免费下载链接】freellmapi7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapi本篇指南以 FreeLLMAPI 仓库的 docs/i18n/README.md 为核心系统讲解该项目如何组织多语言文档树从「以英文为唯一事实来源」的目录镜像布局、逐语言状态表到新增一门语言的完整步骤、让翻译长期可维护的六条规则以及英文原文变动时的协作机制。读完你可以直接上手为该项目提交翻译 PR也能把这套「文档镜像 诚实状态 术语表驱动」的方案复用到自己的开源项目上。一、先厘清两套 i18n文档翻译与界面翻译FreeLLMAPI 的国际化实际上分为两条互不干扰的线理解它们的边界是理解一切后续规则的前提文档翻译本指南的主角位于 docs/i18n/ 目录翻译的是仓库里用户阅读的 Markdown 文档根 README、安装指南、API 参考等。界面字符串翻译仪表盘 UI 的文案位于 client/src/i18n/locales/由独立的流程管理规则写在 docs/i18n/01-translating.md。两条线共享同一套术语约定。正如 docs/i18n/README.md 明确警告的「一个把提供方翻译成提供商、而仪表盘里叫提供方的 README比没有翻译更糟糕」。读者打开应用看到的词和文档里读到的词必须一致否则术语分裂会直接损害信任。二、核心设计以英文为唯一事实来源的目录镜像文档翻译总览 开宗明义English is the source of truth英文是唯一事实来源。该目录下的每一个文件都是仓库其他位置某个英文原件的镜像并且允许甚至预期翻译会稍微滞后于原文——前提是它必须诚实地承认这一点。2.1 镜像布局Mirror Layout每个语言一个目录目录名与仪表盘使用的语言代码完全一致zh-CN、pt-BR、fr等。当前仓库中简体中文是唯一已有实体的语言目录docs/i18n/zh-CN/README.md ← /README.md 的翻译 docs/i18n/zh-CN/docs/README.md ← /docs/README.md 的翻译 docs/i18n/zh-CN/docs/install.md ← /docs/install.md 的翻译这套镜像刻意为之它带来一个可逆的定位能力正向把任意翻译文件路径中的docs/i18n/locale/删除就得到其英文原件的路径反向在英文原件路径上插入docs/i18n/locale/就得到对应的翻译路径。例如docs/i18n/zh-CN/docs/api/01-rest-api.md对应英文原件 docs/api/01-rest-api.md。任何贡献者都能凭这个约定在几秒内完成「翻译 ↔ 原文」的双向跳转。2.2 目录与翻译状态一览截至当前仓库简体中文树已覆盖 4 个核心页面详见 zh-CN/OVERVIEW.md中文文件镜像的英文原件内容zh-CN/README.mdREADME.md项目总览网关做什么、支持的提供方、快速开始、配置zh-CN/docs/README.mddocs/README.md文档树索引页zh-CN/docs/install.mddocs/install.md安装指南Docker Compose、本地搭建、桌面应用zh-CN/docs/api/01-rest-api.mddocs/api/01-rest-api.mdOpenAI 兼容/v1端点的 API 参考此外还镜像了docs/下的多个领域子树deployment、providers、testing、architecture 等各有 OVERVIEW、编号主题文档与 CHANGELOG完整清单见 zh-CN/OVERVIEW.md 的文件索引表。三、翻译状态表诚实优先未翻译不道歉docs/i18n/README.md 用一个状态表逐页标记翻译进度Pagezh-CNREADME.md✅docs/README.md✅docs/install.md✅docs/api/01-rest-api.md✅docs/clients/01-agent-clients.mdEnglishdocs/compression/01-compression-pipeline.mdEnglishdocs/architecture.mdEnglish表格背后的原则值得所有开源维护者借鉴未翻译的页面不是需要道歉的缺口。与其发布一份过时陈旧、却会被读者信以为真的 300 行参考文档翻译不如直接链接到英文原文让读者面对确定的事实。中文 README 中同样体现这一立场——「客户端与编程智能体」「提示词压缩」「架构与内部实现」三篇指南目前只有英文版链接直接指向英文原件并附一行说明指引读者查看完整状态表。四、新增一门语言的完整步骤在 docs/i18n/README.md 中添加一门新语言被压缩为三个清晰步骤创建docs/i18n/locale/并优先翻译根README.md——它是几乎所有读者都会读的第一页单独交付它就是一份完整的贡献。在/README.md顶部的语言栏里加入该语言的链接同时更新其他所有已翻译 README 顶部的语言栏。语言栏的格式在 docs/i18n/OVERVIEW.md 中有示例**English** · [简体中文](https://link.gitcode.com/i/b307120d02b71c4f6f7d7c90fdc839c3)居中放置于 hero 截图上方。实际的根 README 语言栏写法是[English](https://link.gitcode.com/i/736ced6a88c67a0005644cba6453dc8a) · **简体中文**见 zh-CN/README.md 第 18 行。在上面的状态表中增加一列。这一流程刻意保持了「小步、完整、可合并」一门语言的最小可用交付是一页 README 加一个语言栏入口而不是必须一次性翻译完整个文档树。五、让翻译长期可维护的六条规则这是 docs/i18n/README.md 中最具操作价值的部分六条规则逐一规定了翻译的边界5.1 只翻译散文不翻译标记Translate prose, not markup徽章、HTML 表格、图片标签、代码块、CLI 命令保持原样产品名、端点路径、环境变量、模型 ID 同样一字不动。翻译的是句子不是结构——任何改动代码块或徽章的行为都会被 Review 直接打回。5.2 修正相对路径翻译后的 README 位于仓库根目录下三层深处因此所有相对资源路径都必须重新指向英文原件中的写法翻译文件中的写法repo-assets/x.png../../../repo-assets/x.pngdocs/api/01-rest-api.md../../api/01-rest-api.md原文明确警告破损的图片链接是这类提交里最常见的错误。这一点在中文 README 中有大量实例例如 zh-CN/README.md 中的../../../repo-assets/github-hero.png正是从根目录 README 的repo-assets/github-hero.png转换而来。5.3 不复制贡献者头像墙根 README 的贡献者头像列表几乎每次合并都会变动没人愿意在六种语言里同步维护它。翻译版保留标题以维持章节结构的一对一对应然后从标题下方链接到英文 README。中文版 zh-CN/README.md 的「贡献者」小节正是这样处理的。5.4 数字要么同步要么不写提供方数量、词元总量这类数字会持续变动。如果你不打算在每次变更后更新它们就绕开数字去写句子。这解释了为什么中文 README 顶部仍然标注着「每月 74 亿词元、34 家免费提供方、635 个免费端点」同时诚实声明「本翻译可能滞后最新内容以英文 README 为准」。5.5 与仪表盘保持一致某个词一旦在 UI 里出现就采用该语言 JSON 文件里已有的译法。README 与读者即将打开的应用之间的用词一致性优先级高于任何个人的用词偏好。这正是 docs/i18n/01-translating.md 存在的原因。5.6 术语表中文简体的既定约定docs/i18n/01-translating.md 记录了一份在长期 Review 后「定案」的简体中文术语表中文 README 明确要求翻译提交前先过一遍它Englishzh-CN说明Provider提供方不用「提供商」自定义端点、本地 Ollama、社区实例不是厂商Token (LLM)词元国家科技术语委员会公布的术语Token (auth, API keys, URL tokens)令牌绝不译为「词元」这是凭据而非词单位Coding编程不用「编码」读作 encodingExport导出不用「出口」货运义Request size请求大小不用「请求数据量」会被读成多请求聚合量Request body请求正文与 Google Cloud、Cloudflare 中文文档一致Revoke撤销不用「废除」Playground试验台是测试模型的台子不是「试玩台」Balance自定义预设权衡数值滑块本身是「权重」you您不用「你」句子读起来自然时也可省略代词EnglishUI 语言英文不用「英语」界面切换开关涉及书面文本其兄弟标签是「中文」补充约定还包括策略预设是比较级的保留「最」字最快、最稳定、最智能标点用全角。中文术语两侧不加拉丁式空格但嵌入中文句子的拉丁词与数字两侧各留一个空格如API 令牌。5.7 「词元」这个词为何值得专门讨论01-translating.md 单独用一节解释了「词元」这个译名它是国家科技术语委员会发布的术语与「令牌」形成明确区分此前文件曾混淆两者反面意见是大多数中文 AI 产品界面上仍直接显示拉丁文Token因此「词元」对部分用户会显得正式。结论是「已决断并非无人注意」——改它意味着改动大约 25 条字符串应当先开 issue 讨论而不是顺手塞进无关的 PR。5.8 zh-TW 不等于 zh-CN繁体中文刻意与简体术语分歧不应逐词同步Englishzh-TWTokenToken保留拉丁文Provider提供者Playground遊樂場台湾的技术写作保留的拉丁文远比大陆多。更新两份文件之一时另一份里相同的字符串要一并检查但遵循当地惯例而非强行统一。六、当英文原文变化时流程而非强约束docs/i18n/README.md 对「英文变更」的态度相当务实没有任何机制自动强制翻译同步也不应该有——一份过时的翻译总好过一个被阻塞的发布。约定是如果你大幅修改了根 README开一个带i18n标签的 issue让翻译者知道有工作等待认领如果你维护某个翻译关注该标签是最省力的跟进方式。这与状态表「诚实优先」的原则一脉相承翻译滞后是被接受的状态前提是它如实标注了滞后。七、源码侧的保障机制校验脚本与语言注册文档规则之外仓库用两个可执行的组件落实这套约定7.1 界面校验脚本 check-i18nclient/scripts/check-i18n.mjs 是 60 种语言字典的自动校验器通过npm run check:i18n触发定义于 client/package.json 的scripts字段。它做的事情与文档翻译的「数字同步」规则相呼应核对 expectedLocales 与client/src/i18n/locales/下实际 JSON 文件是否一一对应缺文件、多文件都报错以en.json为基准对每种语言检查键完全对齐不允许缺键或多余键校验每个值的类型一致校验{placeholder}占位符名称一致这正是界面字符串中「不要改变占位符」的机器强制版。脚本的定位清晰它保证结构正确性键、类型、占位符但不检查翻译质量所以它输出的成功信息明确提醒——i18n validation passed for N locales and M keys之外你还得亲自读一遍自己的 diff。7.2 语言注册表 locale-config.tsclient/src/i18n/locale-config.ts 是仪表盘的权威语言清单SUPPORTED_LOCALES常量列出 60 种语言代码DEFAULT_LOCALE为enRTL_LOCALES集合标记了ar、he、fa、ur四个从右往左书写的语言。中文 README 的「语言」一节描述了与之配套的运行时行为首次加载自动检测浏览器/系统语言、可在设置中随时切换且选择被记住、RTL 语言自动翻转整个布局、只加载当前语言的词典。这解释了文档翻译目录为何要用与locale-config.ts完全一致的代码命名——两边共用一套语言标识。八、如何开始贡献一份翻译综合 docs/i18n/README.md 与 docs/i18n/01-translating.md一份合格的翻译 PR 的检查清单是先读术语表docs/i18n/01-translating.md 中的中文术语约定对文档与界面同样适用特别核对 UI 里已出现的词。遵循目录镜像在docs/i18n/locale/下按英文原件的路径镜像创建文件。修对相对路径图片与文档链接按「上三层」规则重新指向../../../repo-assets/...、../../api/...。只翻译散文代码块、命令、端点路径、环境变量、模型 ID 原样保留。诚实标注状态未翻译的页面链接英文原文而不是塞一份过时翻译。更新入口与状态表在所有 README 的语言栏加链接并在 docs/i18n/README.md 的状态表加一列。控制 PR 范围尽量一个 PR 只动一门语言60 文件的 diff 极难 Review。翻译意义而非字词英文句子有歧义时先看它在界面上渲染的位置再猜。这套「镜像目录 诚实状态表 术语表驱动 结构校验脚本」的组合正是 FreeLLMAPI 在 60 种界面语言与多语言文档之间保持长期一致、且维护成本可控的关键所在。无论是直接参与该项目的中文翻译还是为自己的项目设计 i18n 文档方案本文覆盖的约定都值得原样借鉴。相关文档翻译工作流主文档docs/i18n/README.md文档翻译总览与约定docs/i18n/OVERVIEW.md界面字符串与中文术语表docs/i18n/01-translating.md简体中文翻译索引docs/i18n/zh-CN/OVERVIEW.md简体中文 README镜像根 READMEdocs/i18n/zh-CN/README.md界面校验脚本client/scripts/check-i18n.mjs语言注册表client/src/i18n/locale-config.ts界面语言词典目录client/src/i18n/locales/【免费下载链接】freellmapi7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.项目地址: https://gitcode.com/GitHub_Trending/fr/freellmapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考