企业官网建设流程全解析

• 文档
• 教程
• 知识库

本篇指南围绕 tldr 仓库的 common-descriptions.md 展开，它是面向 39 种语言翻译者的"通用描述术语表"。tldr 页面中反复出现的Display help、Display version与[Interactive]三类描述，在此统一登记各语言标准译法。读者读完可以掌握：这些通用描述在页面中的规范用法、如何按语言查表取词、以及如何借助表格工具安全地维护这张多语言对照表。

为什么 tldr 需要一张"通用描述"翻译表

tldr 是一个协作式命令行速查表仓库，每个命令页面都由「标题、描述行、若干示例」构成，而--help、--version这类示例几乎出现在每一个命令页中。若各语言翻译者各自发挥，同一句 "Display help" 可能在同一语言内出现多种译法，破坏术语一致性，也增加维护成本。

为此，style-guide.md 的 "Help and version commands" 一节明确规定：

我们通常按顺序将 help 与 version 命令放在页面最后两个示例中，以将更实用的命令放在页面开头；为保持一致性，我们倾向于对这些命令使用通用措辞Display help和Display version。

同时，对于需要进入交互模式的命令，style-guide.md 要求：在进入该模式的示例描述中提及 "interactive"，并且交互命令的描述行以[Interactive]开头，例如[Interactive] Choose a server:。

而 common-descriptions.md 正是为这些被反复使用的措辞提供逐语言的标准翻译，让维护者不必逐页搜索比对。

模板文件的结构：一张按语言行组织的对照表

common-descriptions.md 的核心是一张 Markdown 表格：

• 表头四列：en（英文原文）、Display help、Display version、[Interactive]
• 每一行：一个语言代码及其对应译法
• 空单元格：表示该语言此条目的翻译尚未提供（如bs、lo、ne、no、pt_PT、sr、uk多列为空）

文件共覆盖 39 种语言：ar、bg、bn、bs、ca、cs、da、de、el、es、fa、fi、fr、hi、id、it、ja、ko、lo、ml、nb、ne、nl、no、pl、pt_BR、pt_PT、ro、ru、si、sr、sv、ta、th、tr、uk、uz、zh、zh_TW。

这与仓库的页面目录结构一一对应：仓库根目录下以pages.<语言代码>命名的目录（如 pages.fr、pages.zh、pages.pt_BR）共同构成了多语言页面体系，scripts/_common.py 中的get_pages_dirs()正是通过扫描pages前缀目录来发现全部语言。

完整对照表（common-descriptions.md 原文）

下表完整继承自 common-descriptions.md，翻译页面时可直接查表取词：

三种通用描述的语义与页面用法

Display help：帮助示例的标准措辞

按 style-guide.md 的约定，帮助示例应放在页面倒数第二个位置，且使用通用措辞。在中文页面（zh）中对应 "显示帮助"，这在 pages.zh/common 下的页面中得到大量应用，例如：

• pages.zh/common/3d-ascii-viewer.md 第 26 行
• pages.zh/common/a2ping.md 第 30 行
• pages.zh/common/btop.md 第 32 行

页面中对应片段形如：

- 显示帮助： `command --help`

Display version：版本示例的标准措辞

同样地，版本示例应放在页面最后一个位置，中文译作 "显示版本"（zh_TW 为 "顯示版本"）。与Display help不同，部分语言至今尚未提供该条目译法（如fa、pt_PT），此时可在查表后自行补译并回填到模板中。

[Interactive]：交互模式的描述标记

style-guide.md 对交互模式的定义是：命令本身进入一个子环境运行命令、且提示符无法访问$PATH中的程序。进入该模式的示例需要：

1. 在进入交互模式的示例描述中明确提及 "interactive"；
2. 交互式命令的描述行以[Interactive]开头标记。

例如英语写为[Interactive] Choose a server:，中文对应 "「[交互式] 选择服务器：」"（zh_TW 为[互動式]）。

如何安全地维护这张多语言表格

common-descriptions.md 自带官方建议的工作流——使用 tableconvert.com 进行可视化编辑：

1. 导入：将当前表格粘贴导入；
2. 编辑：在 WYSIWYG 编辑器中增删语言行、补全空单元格；
3. 导出：导出为 Markdown 表格并替换文件内容。

同时文档特别提醒一个导出后遗症：表头的左对齐会被丢失，需要手动恢复，即把|----改回|:---。这是 Markdown 表格语法的一部分：|---与|:---分别表示默认对齐与左对齐，客户端渲染时对齐方式会影响显示效果。

通用描述模板在仓库脚本中的消费方式

翻译模板并不是孤立文档，仓库中的维护脚本会直接解析它们。scripts/_common.py 的get_templates()读取contributing-guides/translation-templates/<文件名>，按###语言标题解析出每种语言的模板文本，供各脚本复用：

template_file = root / "contributing-guides/translation-templates" / filename with template_file.open(encoding="utf-8") as f: lines = f.readlines()

例如 scripts/set-more-info-link.py 会加载more-info-link.md中的逐语言 "More information" 链接模板，用真实链接替换https://example.com占位符后写回页面；scripts/set-alias-page.py 则加载alias-pages.md模板生成别名页面。可见，contributing-guides/translation-templates 目录下的每份模板（含 common-arguments.md、alias-pages.md、more-info-link.md）都是脚本自动化的数据源，而 common-descriptions.md 主要面向人工翻译参考。

配套的 common-arguments.md 则负责另一类通用元素——命令示例中的占位符（如path/to/file、username、port、value）的逐语言翻译，两者配合可覆盖页面中几乎全部的高频文本。该文件还附有一条重要注意事项：阿拉伯语（ar）和波斯语（fa）页面中的占位符不应翻译，以避免从右到左文本渲染时产生倒置错乱。

翻译与校验实践建议

1. 先查表，后动手：编写任何语言的帮助、版本、交互描述前，先对照上表确认已有标准译法；空白单元格则代表待翻译条目，可在提交中一并补全。
2. 遵循各语言的独立规范：style-guide.md 还针对具体语言规定了语法细节（如法语描述需用第三人称直陈式现在时、葡萄牙语示例描述须以第三人称动词开头、中文需注意中英文混排空格与全角标点等），通用描述应在此框架内使用。
3. 用 linter 校验：页面格式由 linter 强制约束，可通过tldr-lint本地校验，详情见 style-guide.md 的 "There is a linter" 小节。
4. 不要机器批量改动：style-guide.md 明确要求只翻译自己能够自信阅读与校对的语言，避免对不熟悉的语言进行机器生成或批量编辑。

通过这张统一术语表，tldr 的数十种语言页面得以在"帮助 / 版本 / 交互"三个高频场景上保持措辞一致，这也是 tldr 多语言协作体系能够低摩擦运转的关键细节之一。

• 文档
• 教程
• 知识库