FreeLLMAPI 多语言文档体系：翻译工作流、目录镜像约定与术语一致性实战指南-酒店常州论坛

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.md	README.md	项目总览：网关做什么、支持的提供方、快速开始、配置
zh-CN/docs/README.md	docs/README.md	文档树索引页
zh-CN/docs/install.md	docs/install.md	安装指南：Docker Compose、本地搭建、桌面应用
zh-CN/docs/api/01-rest-api.md	docs/api/01-rest-api.md	OpenAI 兼容`/v1`端点的 API 参考

此外还镜像了docs/下的多个领域子树（deployment、providers、testing、architecture 等，各有 OVERVIEW、编号主题文档与 CHANGELOG），完整清单见 zh-CN/OVERVIEW.md 的文件索引表。

三、翻译状态表：诚实优先，未翻译不道歉

docs/i18n/README.md 用一个状态表逐页标记翻译进度：

Page	zh-CN
`README.md`	✅
`docs/README.md`	✅
`docs/install.md`	✅
`docs/api/01-rest-api.md`	✅
`docs/clients/01-agent-clients.md`	English
`docs/compression/01-compression-pipeline.md`	English
`docs/architecture.md`	English

表格背后的原则值得所有开源维护者借鉴：未翻译的页面不是需要道歉的缺口。与其发布一份过时陈旧、却会被读者信以为真的 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.png`
`docs/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 明确要求翻译提交前先过一遍它：

English	zh-CN	说明
Provider	提供方	不用「提供商」；自定义端点、本地 Ollama、社区实例不是厂商
Token (LLM)	词元	国家科技术语委员会公布的术语
Token (auth, API keys, URL tokens)	令牌	绝不译为「词元」；这是凭据而非词单位
Coding	编程	不用「编码」（读作 encoding）
Export	导出	不用「出口」（货运义）
Request size	请求大小	不用「请求数据量」（会被读成多请求聚合量）
Request body	请求正文	与 Google Cloud、Cloudflare 中文文档一致
Revoke	撤销	不用「废除」
Playground	试验台	是测试模型的台子，不是「试玩台」
Balance（自定义预设）	权衡	数值滑块本身是「权重」
you	您	不用「你」；句子读起来自然时也可省略代词
English（UI 语言）	英文	不用「英语」；界面切换开关涉及书面文本，其兄弟标签是「中文」

补充约定还包括：策略预设是比较级的，保留「最」字（最快、最稳定、最智能）；标点用全角（，。：；）；中文术语两侧不加拉丁式空格，但嵌入中文句子的拉丁词与数字两侧各留一个空格（如API 令牌）。

5.7 「词元」这个词为何值得专门讨论

01-translating.md 单独用一节解释了「词元」这个译名：它是国家科技术语委员会发布的术语，与「令牌」形成明确区分（此前文件曾混淆两者）；反面意见是大多数中文 AI 产品界面上仍直接显示拉丁文Token，因此「词元」对部分用户会显得正式。结论是「已决断，并非无人注意」——改它意味着改动大约 25 条字符串，应当先开 issue 讨论，而不是顺手塞进无关的 PR。

5.8 zh-TW 不等于 zh-CN

繁体中文刻意与简体术语分歧，不应逐词同步：

English	zh-TW
Token	`Token`，保留拉丁文
Provider	提供者
Playground	遊樂場

台湾的技术写作保留的拉丁文远比大陆多。更新两份文件之一时，另一份里相同的字符串要一并检查，但遵循当地惯例而非强行统一。

六、当英文原文变化时：流程而非强约束

docs/i18n/README.md 对「英文变更」的态度相当务实：没有任何机制自动强制翻译同步，也不应该有——一份过时的翻译总好过一个被阻塞的发布。约定是：

如果你大幅修改了根 README，开一个带i18n标签的 issue，让翻译者知道有工作等待认领；
如果你维护某个翻译，关注该标签是最省力的跟进方式。

这与状态表「诚实优先」的原则一脉相承：翻译滞后是被接受的状态，前提是它如实标注了滞后。

七、源码侧的保障机制：校验脚本与语言注册

文档规则之外，仓库用两个可执行的组件落实这套约定：

7.1 界面校验脚本 check-i18n

client/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.ts

client/src/i18n/locale-config.ts 是仪表盘的权威语言清单：SUPPORTED_LOCALES常量列出 60 种语言代码，DEFAULT_LOCALE为en，RTL_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 文档方案，本文覆盖的约定都值得原样借鉴。

企业官网建设流程全解析