• 文档
• 教程
• 知识库

本文以 tldr 仓库中的阿拉伯语别名页pages.ar/common/..md为切入点，完整还原该页面的结构与语义，并延伸讲解 tldr 项目的别名页（alias page）文档体系——包括英文源页、source命令完整文档、40 余种语言的翻译模板、自动化生成脚本与风格指南规范。读完本文，你将能看懂任意一条 tldr 别名页的构造逻辑，掌握用set-alias-page.py创建与同步别名页的实战方法，并彻底理解.与source的关系。

一、关联文档全景：pages.ar/common/..md到底写了什么

仓库中pages.ar/common/目录存放阿拉伯语（Arabic，locale 为ar）的common平台命令页。其中..md文件的完整内容如下：

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

这份文档只有 6 行，却是 tldr 别名页（alias page）的标准范式，逐行解析如下：

这份阿拉伯语页面与英文源页 pages/common/..md 逐字段一一对应。英文版原文为：

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

对比可知，别名页的核心设计意图非常明确：它不重复描述命令用法，而是用一句话告诉用户“我是谁的别名”，并给出tldr <原命令>让用户一键跳到真正的文档。这保证了同一命令族在 tldr 中只有一个信息源，避免重复维护。

二、被别名指向的原命令：source完整文档

既然.是source的别名，那么原命令文档 pages/common/source.md 才是实际承载用法的地方。该页说明为 "Execute commands from a file in the current shell"（在当前 shell 中执行文件中的命令），并给出五种用法：

source {{path/to/file}}

直接对给定文件求值（在当前 shell 中执行，而非子 shell）。

source {{path/to/file}} {{argument1 argument2 ...}}

带参数求值文件，参数可在被加载的脚本中作为位置参数使用。

source {{file}}

从$PATH中搜索并求值文件。

source -p {{path/to/directory1:path/to/directory2:...}} {{file}}

在指定的目录集合（冒号分隔）中搜索并求值文件。

. {{path/to/file}}

用.等价替代source的写法——这正是别名页..md中标题.的由来：.就是 POSIX shell 中source的同义写法，在 Bash 中两者行为一致。

此外该页还提供了更多信息链接到 GNU Bash 手册（More information: <https://www.gnu.org/software/bash/manual/bash.html#index-source>）。当你在交互式 shell 中执行tldr source时，看到的正是这份文档。

三、别名页翻译模板体系：40 余种语言共享同一骨架

pages.ar/common/..md并非手工自由发挥，而是严格套用了别名页翻译模板。仓库中的 contributing-guides/translation-templates/alias-pages.md 记录了这套由 tldr 社区在 PR #5368 中确定、供全部语言共用的模板清单。其中阿拉伯语（ar）模板原文为：

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

将该模板中的三处example占位符分别替换为“别名命令名”“原命令名”“文档命令名”，就得到了..md这份页面。该模板文件覆盖了en、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等语言，保证了“标题—别名说明—跳转命令”三要素在任何语言下都结构一致，便于客户端与 lint 工具统一解析。

从源码结构看，正是这种严格的模板一致性，使得下面的自动化同步脚本成为可能。

四、别名页的自动化生成：scripts/set-alias-page.py

别名页可以由脚本自动创建与同步，脚本位于 scripts/set-alias-page.py，基于仓库scripts/_common.py提供的路径发现、模板加载与暂存能力。其命令行参数如下：

脚本的核心机制可以从源码中直接确认：

• generate_alias_page_content()（set-alias-page.py）读取对应语言的模板，按顺序把三处example占位符分别替换为页面标题、原命令名、文档命令名；
• get_alias_command_in_page()（set-alias-page.py）反向解析已有页面，校验其是否严格符合别名模板（精确模式下去除占位符后必须与模板逐字一致），并提取original_command与documentation_command；
• sync_alias_page_to_locale()将英文别名页内容写入各语言目录对应的路径，例如将common/..md同步到pages.ar/common/..md；
• main()中-p分支会启动交互式向导（提示输入标题、原命令、文档命令），确认后调用set_alias_page()写入文件。

值得注意：脚本文档字符串中明确提示该脚本的同步模式会产生较多误报，因此不建议直接全量使用-S；如需使用，应配合-l LANGUAGE限定语言，并仅暂存、核对后再提交。这也从侧面印证了模板精确匹配（-i/--inexact参数控制）在别名页体系中的重要性——pages.ar/common/..md之所以能被自动识别和同步，正是因为它与模板严格一致。

五、别名页编写规范：style-guide 中的约定

仓库的风格指南 contributing-guides/style-guide.md 对别名页有明确的成文规范：

• 当某命令可以用其他名字调用时（例如vim可以通过vi调用），可以创建别名页，将用户指向原命令名；
• 标准说明行格式为> This command is an alias of original-command-name.，随后是查看原命令文档的条目与tldr <原命令>命令；
• 预翻译好的多语言别名页模板统一存放于 alias-pages.md；
• 针对 PowerShell 还定义了三种特殊别名场景（见 style-guide.md）：
  1. 取代原有 cmd 命令（如cd是Set-Location的别名）：需要在原命令页第二行加入“In PowerShell, this command is an alias ofSet-Location”类说明；
  2. 仅 PowerShell 可用的新别名（如ni之于New-Item）：套用标准别名模板，但需在说明中加入 “In PowerShell,” 字样；
  3. 与其他程序冲突的别名（如curl/wget之于Invoke-WebRequest）：需提供判定当前命令指向的说明。

对pages.ar/common/..md而言，它属于最简单的第一种情形：.就是 Bash/POSIX shell 中source的别名，不涉及平台冲突，因此直接采用标准模板即可。

六、如何在客户端中使用这些页面

别名页最终服务的是 tldr 客户端。根据 pages/common/tldr.md，你可以：

• 直接查看源命令文档：tldr source（这正是..md页面中给出的命令）；
• 查看别名页本身：tldr .（客户端会将.解析为对应页面pages/common/..md）；
• 指定语言查看：tldr --language ar .（若阿拉伯语版本存在则显示pages.ar/common/..md，否则回退英文，语言参数行为见 CLIENT-SPECIFICATION.md）；
• 指定平台查看：tldr --platform common .。

小结

一条只有 6 行的阿拉伯语别名页pages.ar/common/..md，背后是一整套完整的工程体系：英文源页 pages/common/..md、承载真实用法的 pages/common/source.md、40 余种语言共享的 alias-pages.md 模板、自动生成与同步的 set-alias-page.py 脚本，以及 style-guide.md 中的别名页规范。理解这一体系后，你既能在 tldr 中快速定位任何别名命令的真实文档，也能在需要时按同样的模板为新的命令别名贡献页面——而这一切的核心原则始终是：别名页只负责“指路”，不重复造信息。

• 文档
• 教程
• 知识库