Databasus 多语言 README 同步机制全解：assets/readme 目录结构与 Agent 工程规范-开发者社区

数据库
灾备

【免费下载链接】databasus

PostgreSQL backup tool with Point-In-Time-Recovery and restore verification

项目地址：https://gitcode.com/gh_mirrors/po/databasus

Databasus 是开源的 PostgreSQL 备份工具（同时支持 MySQL、MariaDB、MongoDB，内置时间点恢复 PITR 与恢复验证），其英文 README 被翻译为俄语、西班牙语、葡萄牙语、中文、法语五种语言，统一存放在 assets/readme/ 目录下。assets/readme/AGENTS.md 正是这套多语言文档流水线的"工程规范说明书"：它规定了翻译副本与英文原文之间必须保持的同步纪律、目录结构与相对路径换算规则、锚点（anchor）推导规则、语言使用边界与翻译质量标准。阅读并遵循这份规则，是维护 Databasus 六语种文档不脱节、让读者真正能照着安装命令操作的前提。

这个目录解决什么问题

英文 README 位于仓库根目录 README.md，而翻译副本则统一放在assets/readme/下，每个语言一个文件：

README.ru.md（俄语）
README.es.md（西班牙语）
README.pt.md（葡萄牙语）
README.zh.md（中文）
README.fr.md（法语）

英文原版保留在仓库根目录，assets/readme/下只放翻译副本。该目录同时配有AGENTS.md与CLAUDE.md两份 Agent 规则文档，说明这套翻译流水线是仓库内"AI 协作工程化"的一部分：人类与 Agent 在改动文档时，都必须遵守同样的同步纪律。从根 AGENTS.md 的文件清单可以看到，assets/readme/AGENTS.md被列为与 backend/AGENTS.md（Go + Gin + GORM 后端）、agent/verification/AGENTS.md（验证代理 CLI）、frontend/AGENTS.md（React 前端）、website/AGENTS.md（营销网站）平级的模块级规则文档，负责约束整个 README 翻译子系统。

同步规则（critical）：英文改动必须落进全部 5 份翻译

这份规则文档的开篇就定下一条最高优先级纪律：

任何对/README.md的改动，都必须同时应用到这里的全部 5 份副本——包括结构、标题、链接、代码块、徽章（badge）。

理由非常实际：一份落后于英文原文的翻译，比没有翻译更糟——读者会照着过期的安装命令操作。文档特别点出一个最容易出错的区段：README 中的## 🛡️ Security & reliability engineering（安全与可靠性工程）章节。由于根目录 AGENTS.md 要求该章节必须与项目真实的安全实践保持一致，因此对它的实质性修改一旦发生，就会同时落进 6 个文件（英文原文 + 5 份翻译）。

从仓库实际内容看，这一点确实成立：README.md 中的安全章节详细描述了 CodeQL、CodeRabbit、gitleaks、semgrep、Trivy、Dependabot、Dependency Review 等多层安全流水线，而 assets/readme/README.zh.md 的中文版逐条对应；根 AGENTS.md 的 Security 小节则明确写着"README 的安全章节是这些实践面向公众的版本——实质内容变化时两者必须保持一致，该章节与 README 其余部分一样存在于 6 种语言中"。

结构镜像：每个文件逐节对应英文原文

每个翻译文件都必须精确镜像英文 README：

相同的章节、相同的顺序
相同的标题层级
标题中相同的 emoji
相同的列表结构（bullet structure）
相同的水平分割线
相同的 HTML 块

还有一个容易忽略的细节：功能特性区里的### 📦 Installation简介块（teaser）与正文完整的## 📦 Installation章节在英文原文中是重复出现的，翻译时必须保留这种重复，不能"好心"删掉。

对照中文版 assets/readme/README.zh.md 可以验证：其## ✨ 功能特性、## 📦 安装、## 🚀 使用、## 🛡️ 安全与可靠性工程、## 📝 许可证、## 🤝 参与贡献的章节顺序与英文 README.md 完全一致，标题 emoji 也一一对应。

字节级一致：命令、配置与徽章绝不能"意译"

assets/readme/AGENTS.md列出了一批必须与英文字节级相同（byte-identical）的内容：

代码块（命令、YAML、块内注释）
shields.io 徽章 URL 及其 alt 文本
行内代码
图片的alt/width属性
产品名与工具名
版本号
端口号
文中引用的英文界面文案（如使用步骤里的"New Database"——界面是英文的，文档要原样引用）

例如中文版 assets/readme/README.zh.md 中的密码重置命令docker exec -it databasus ./main --new-password="YourNewSecurePassword123" --email="owner@example.com"与英文原文逐字符一致，端口4005、镜像名databasus/databasus:latest也原样保留。这条规则的深层逻辑是：安装命令、配置片段是读者会直接复制执行的内容，任何"润色"都可能引入不可执行的差异。

路径规则：翻译文件深一层的相对路径换算

翻译文件位于assets/readme/，比英文 README（仓库根目录）深一层，因此文档内的相对链接必须相应换算：

目标	相对路径
图片	`../logo.svg`、`../dashboard-dark.svg`、`../dashboard.svg`、`../healthchecks.svg`
仓库文件	`../../LICENSE`、`../../deploy/helm/README.md`
英文 README	`../../README.md`

这些路径在中文版 assets/readme/README.zh.md 中都能找到实证，例如第 13 行的../../LICENSE、第 20 行的../../README.md、第 40-42 行的../dashboard-dark.svg与../dashboard.svg，以及第 247 行指向 deploy/helm/README.md 的../../deploy/helm/README.md。图片文件确实存在于 assets/ 下（logo.svg、dashboard-dark.svg、dashboard.svg、healthchecks.svg）。

网站链接：语言前缀与固定锚点

翻译文档中出现的databasus.com链接，规则要求携带语言前缀并保留结尾斜杠：

https://databasus.com/<locale>/storages/
https://databasus.com/<locale>/faq/#backup-databasus

其中锚点 ID（#backup-databasus、#oss-programs）在所有语言中保持完全一致，绝不能翻译；而https://databasus.com/contribute在官网上没有翻译版本，因此不加语言前缀。中文版 assets/readme/README.zh.md 中的https://databasus.com/zh/storages/、https://databasus.com/zh/faq/#backup-databasus等链接即遵循此规则。

页内锚点：与官网不同，GitHub 锚点由标题自动推导

这是这份规则里技术性最强的部分之一。官网页面的锚点在各语言间保持一致，但 GitHub 仓库内的锚点不同：GitHub 由标题文本自动推导锚点，因此翻译后的标题会生成翻译后的锚点。由于没有外部文件链接到这些翻译文件的章节内部，所以每个文件的迷你目录（mini-TOC）和正文内链只需指向本文件自己的 slug。

slug（锚点）推导规则：

全小写
去掉标点
去掉 emoji，但 emoji 两侧的空格会变成一个连字符
其余空格变为连字符
西里尔字母（Cyrillic）与中日韩文字（CJK）原样保留

文档给出了两个具体示例：

## ✨ Features→#-features
## 🛡️ Security & reliability engineering→#️-security--reliability-engineering（变体选择符 variation selector 会保留在锚点中）

在中文版中可以验证：## ✨ 功能特性的锚点就是#-功能特性（中文原样保留、emoji 变连字符），与 assets/readme/README.zh.md 迷你目录中的写法一致。掌握这条规则，就能预测 GitHub 页面上任何一个翻译标题的跳转链接，而不必每次手工查看。

语言使用边界：翻译文件与仓库内"仅英文"规则的关系

仓库范围内有一条总规则：代码、注释、标识符、日志、提交信息一律使用英文。但翻译文件是例外中的例外，其边界被严格划定：

翻译内容本身使用目标语言（俄语、西班牙语、葡萄牙语、中文、法语）
6 个语言切换器标签（English、Русский、Español、Português、中文、Français）也出现在根 README.md，作为例外保留
该目录下除此之外的一切都保持英文：包括提交信息与本规则文档本身
文件名只携带语言代码（locale code），如README.zh.md

根 AGENTS.md 给出了允许翻译内容出现的全部五个位置：网站页面文案（website/app/[lang]/*/content/<locale>.tsx）、README 翻译（assets/readme/README.<locale>.md）、根 README 的语言切换器标签、前端界面字典（frontend/src/shared/i18n/locales/<locale>.ts）、以及 humanizer 技能中引用的示例对。这意味着assets/readme/是这份白名单上唯一的"文档翻译区"。

从仓库文件系统看，前端字典目录 frontend/src/shared/i18n/locales/ 下确实存放着en.ts、es.ts、fr.ts、pt.ts、ru.ts、zh.ts六个界面字典文件，与 README 翻译的六语种布局相呼应——界面文案与 README 翻译共享同一套语言规范。

翻译质量：从"逐字翻译"到"编辑式翻译"

assets/readme/AGENTS.md明确引用 website/AGENTS.md 的 "Translation quality" 章节，并逐条适用。核心要求是：翻译是目标语言的编辑式成文（edited copy），不是逐字对应（word-for-word）。关键质量约束包括：

不硬译（No calques）：保留英文语序的直译、逐字渲染英文结构，都必须重写
不官腔、不注水（No bureaucratese）：删掉膨胀动词与自我吹捧的结尾句
不重复（No repeats）：不在相邻句子中复述同一列表或同一动词
每个语言有自己的约定：
- 俄语用「е」不用「ё」，数字写法如「2-х минут」
- 西班牙语用 usted 敬称，「copia de seguridad」是标题与正文的标准术语
- 葡萄牙语为巴西葡萄牙语（pt-BR），用进行时（«está rodando»）而非欧式（«está a correr»）
- 法语用 vous 敬称，百分号前保留空格（«99 %»）
- 中文用「你」而非「您」（标题也如此）、全文使用全角标点（，。：）、每个中日韩字符与拉丁字母交界处保留一个空格

website/AGENTS.md 还给出了各语言标题的"最高搜索量规范形"：ru «резервное копирование PostgreSQL»、es «copia de seguridad de PostgreSQL»、pt «backup PostgreSQL»、fr «sauvegarde PostgreSQL»、zh «PostgreSQL 备份»——标题与 h1/h2 瞄准高频检索词组，同义词（如 zh 的「数据库备份」）放进正文。此外还有一条"文案英文保留"规则：产品统计数字（Docker pulls、GitHub stars 等）必须在全部 6 种语言和页面上所有重复块之间保持同步；品牌导航项（Slack、Google Drive、Databasus vs X）与引用的界面选项名（"After backup"、"Scheduled verification"、"Hourly"）按设计在所有语言中保持英文，因为界面本身就是英文的，文档必须原样引用。

这份规范在仓库中的纵深验证

assets/readme/AGENTS.md不是孤立的存在，它与仓库其他部分的工程实践互相咬合：

根规则引用：AGENTS.md 将assets/readme/AGENTS.md描述为"根 README 的翻译副本"的治理规则，并规定每处受影响的模块在改动时都要接受模块级文档与本文件的双重审查（见 AGENTS.md 的强制合规审查章节）。
网站翻译同源：website/AGENTS.md 描述了 Next.js 网站的 5 语种全页面副本翻译方案（app/[lang]/<path>/content/<locale>.tsx），与 README 翻译共享相同的语言质量标准；两者共同构成 Databasus 完整的"文档多语言矩阵"（README 6 语言 + 官网 5 语言 + 前端界面 6 字典）。
界面字典联动：根 AGENTS.md 提到的前端界面字典 frontend/src/shared/i18n/locales/ 使用与 README 相同的术语体系（中文：备份、存储、通知渠道、工作区、恢复、可用性检查、恢复验证、验证代理），保证文档能原样引用界面文案。
真实翻译成果：assets/readme/README.zh.md 是这套规范的直接产物，其章节结构、emoji 标题、命令代码块、相对路径换算、语言切换器标签与锚点写法均可对照上文规则逐一验证。