• 文档
• 教程
• 知识库

本篇文章以 tldr 仓库中的阿拉伯语别名页面 pages.ar/common/chdir.md 为核心，系统讲解 tldr 速查手册的“别名页面（Alias Page）”设计：为什么需要它、它的模板化结构与多语言同步方式、以及它如何引导读者获取原命令cd的完整文档。读完本文，你将掌握别名页面的完整生成链路（模板占位符替换 → 多语言同步脚本 → 命名一致性校验），并能独立阅读与使用这类页面。

一、什么是别名页面：一个命令，一份文档

在命令行生态中，许多工具会为常用命令提供“别名（alias）”。例如chdir就是cd的别名——两者执行完全相同的功能。如果 tldr 为每个别名都维护一套完整、独立的文档，必然造成大量重复内容，且一旦原命令文档更新，别名页还需要同步维护。

tldr 的解决方案是引入别名页面（alias page）：它不重复描述命令用法，只做三件事：

1. 声明“该命令是某命令的别名”；
2. 用一句话指引读者；
3. 给出tldr <原命令>的命令，让读者直接查看原命令的完整文档。

英文基准页 pages/common/chdir.md 就是一个标准范例：

# chdir > This command is an alias of `cd`. - View documentation for the original command: `tldr cd`

而本文主体 pages.ar/common/chdir.md 则是它的阿拉伯语翻译，仅替换了描述与指引文本：

# chdir > هذا الأمر هو اسم مستعار لـ `cd`. - إعرض التوثيقات للأمر الأصلي: `tldr cd`

对比可见，别名页面的标题（# chdir）与原命令名（`cd`）保持不变，变化的是描述句与列表项的本地化措辞。

二、模板化：四十余种语言共用一套结构

别名页面并非随意书写，而是严格遵循 tldr 项目的统一模板。仓库中的 contributing-guides/translation-templates/alias-pages.md 保存了所有语言的别名页面模板（该模板体系由 tldr 项目在 PR #5368 中讨论确定，文档注明模板可按需调整）。

以 en 模板和 ar 模板为例：

### en # example > This command is an alias of `example`. - View documentation for the original command: `tldr example`

### ar # example > هذا الأمر هو اسم مستعار لـ `example`. - إعرض التوثيقات للأمر الأصلي: `tldr example`

可以看出，阿拉伯语模板与 pages.ar/common/chdir.md 的结构完全吻合，其中example只是占位符，实际页面中会被替换为真实的命令名。这种模板化设计保证了：

• 结构一致性：无论哪种语言，别名页面都保持“标题 → 别名声明 → 查看原命令文档 →tldr指令”的四行骨架；
• 可机器校验：脚本可以据此区分“标准别名页面”与“非标准页面”；
• 多语言同步：新增命令时，各语言翻译只需对照模板做最小改动。

三、深入原命令：cd的完整速查文档

别名页面的价值最终体现在它能引导读者抵达原命令文档。对chdir而言，目的地是cd的速查页 pages.ar/common/cd.md：

# cd > تغيير مجلد العمل الحالي. > لمزيد من التفاصيل: <https://www.gnu.org/software/bash/manual/bash.html#index-cd>. - اللانتقال إلى المجلد المذكور: `cd {{path/to/directory}}` - اللانتقال إلى المجلد الأعلى للمجلد الحالي: `cd ..` - الانتقال إلى المجلد الرئيسي للمستخدم الحالي: `cd` - الانتقال إلى المجلد الرئيسي للمستخدم المذكور: `cd ~{{username}}` - الانتقال إلى المجلد الذي تم اختياره سابقًا: `cd -` - الانتقال إلى مجلد الجذر: `cd /`

该页面完整覆盖了cd的六大核心用法，与英文基准页 pages/common/cd.md 一一对应：

页面顶部还给出了 Bash 手册的官方链接（More information行），符合 tldr 对“简练 + 附官方链接”的文档定位。这也解释了别名页为何只写一行tldr cd：与其复制这六条用法，不如让读者一键直达权威页面。

四、别名页面的生成与同步：set-alias-page.py

别名页面在仓库中并非只能手工编写，tldr 提供了专门的维护脚本 scripts/set-alias-page.py，用于生成、更新与多语言同步别名页面。

4.1 占位符替换的核心机制

脚本的核心函数generate_alias_page_content()（见 scripts/set-alias-page.py）读取对应语言的模板，依次完成三次example占位符替换：

result = template_content.replace(template_command, page_content.title, 1) # 标题 result = result.replace(template_command, page_content.original_command, 1) # 原命令名 result = result.replace(template_command, page_content.documentation_command) # tldr 指令中的命令

即：模板中第一处example替换为页面标题，第二处替换为被别名的原命令（出现在描述句的反引号中），其余位置全部替换为文档命令（出现在`tldr ...`中）。对chdir而言，替换结果就是# chdir、`cd`、tldr cd。

4.2 常用维护命令

脚本支持交互式创建与批量同步两种工作方式：

# 交互式创建/更新一个别名页面（如 osx/gsum） python3 scripts/set-alias-page.py -p osx/gsum # 以英文页为基准，同步所有语言的别名页面 python3 scripts/set-alias-page.py -S # 仅同步巴西葡萄牙语（pt_BR）的别名页面 python3 scripts/set-alias-page.py -S -l pt_BR # 同步并 git stage 变更、或先预览改动（dry-run） python3 scripts/set-alias-page.py -Ss python3 scripts/set-alias-page.py -Sn

需要说明的是，脚本文档明确提示：-S同步模式可能产生较多误报（false positives），因此不建议直接使用同步选项；如需使用，建议用-l LANGUAGE限定语言，并只暂存、提交人工核实过的变更。这与我们看到的仓库现状一致——各语言别名页面大多结构规整、与模板严格对齐。

五、平台差异：不同平台上的chdir

别名页面还按操作系统平台分化。chdir在仓库中不仅存在于common（跨平台通用）目录，还出现在 DOS 与 Windows 平台目录中：

• pages/dos/chdir.md：标题为# CHDIR（DOS 中的大写约定），声明其为CD的别名，并使用带平台参数的指令`tldr {{[-p|--platform]}} dos cd`指向 DOS 平台下的cd页；
• pages/windows/chdir.md：除指向 Command Prompt 的cd外，还额外说明在 PowerShell 中chdir等价于Set-Location，并分别给出tldr cd与tldr set-location两条指引，同时附上微软官方文档链接；
• 阿拉伯语对应页面 pages.ar/dos/chdir.md 与英语 DOS 页保持同构，仅本地化描述文本。

这体现了 tldr 的另一设计原则：同一命令在不同平台可能有不同语义，因此按平台分目录组织，并在别名页中显式声明平台归属。

六、质量保障：命名与模板的一致性校验

别名页面还纳入 tldr 的自动化检查流程。以 scripts/wrong-filename.py 为例，该脚本遍历所有pages*目录下的.md文件，校验文件名与页面标题（H1）是否一致：它会把文件名中的-替换为空格、统一小写后与首行# 标题归一化比较，不一致则写入inconsistent-filenames.txt。chdir.md的 H1 恰好是chdir（DOS 平台为CHDIR，属于平台特定大写约定），可顺利通过该校验。

此外，别名页面结构是否严格匹配模板，也是脚本get_alias_command_in_page()（见 scripts/set-alias-page.py）判定“该页面是否为别名页”的依据：它要求页面恰好包含一条“别名声明行”和一条`tldr ...`指令行，否则返回空内容，视为非别名页。这说明别名页的四行骨架不是装饰，而是被工具链当作结构化数据解析的。

七、作为读者：如何高效使用这类页面

如果你在终端中安装了任一 tldr 客户端，遇到chdir时有两种打开方式：

1. 直接查看别名页本身——它会告诉你“chdir是cd的别名”，并给出tldr cd的指引；
2. 执行tldr cd（或按平台执行tldr dos cd/tldr set-location），直接打开原命令的完整速查文档，获得上文第三节列出的全部六种用法。

若你是贡献者，想为某个新命令补充别名页，可参照 contributing-guides/translation-templates/alias-pages.md 中对应语言的模板（阿拉伯语贡献者可参考 ar 模板与 pages.ar/common/chdir.md 的实际成品），或直接运行python3 scripts/set-alias-page.py -p 平台/命令走交互式向导，脚本会自动完成占位符替换并写入对应语言目录。

小结

从 pages.ar/common/chdir.md 这一个只有四行的阿拉伯语文件出发，可以完整看到 tldr 别名页面的设计哲学：用最少的重复信息，把用户精确引导到原命令的完整文档。支撑这一设计的是三套基础设施——多语言模板文件（alias-pages.md）、模板驱动的生成/同步脚本（set-alias-page.py）以及命名一致性校验脚本（wrong-filename.py）。理解了这条链路，你既能快速看懂仓库中任何一个语言、任何一个平台的别名页面，也具备了为 tldr 贡献新别名页的完整知识。

• 文档
• 教程
• 知识库