企业官网建设流程全解析

• 文档
• 教程
• 知识库

本篇文章以仓库中的保加利亚语别名页 pages.bg/windows/h.md 为切入点，系统讲解 Windows PowerShell 命令h与Get-History的别名关系、tldr 项目别名页（Alias Page）的模板设计与生成逻辑。读完本文，你将掌握如何阅读与维护这类「一句话跳转」页面，也能顺着源码理解别名页的自动生成与多语言同步机制。

一、pages.bg/windows/h.md：一个完整的保加利亚语别名页

仓库中 pages.bg/windows/h.md 的内容非常精炼，全文如下：

# h > Тази команда е псевдоним на `Get-History`. - Виж документацията за оригиналната команда: `tldr Get-History`

逐行解读这段内容：

• # h：页面的标题，即命令名本身，说明这是一份针对 Windows 命令h的 tldr 页面；
• > Тази команда е псевдоним наGet-History.：保加利亚语描述句，意为「此命令是Get-History的别名」，直接点明h与 PowerShell 原命令Get-History的等价关系；
• - Виж документацията за оригиналната команда:：操作项描述，意为「查看原命令的文档」；
• `tldr Get-History`：可执行的跳转命令，用户只需在终端执行该命令即可查看原命令的完整文档。

该页面与英文页 pages/windows/h.md 在结构上完全同构（英文对应描述为 "This command is an alias ofGet-History." 与 "View documentation for the original command:"），区别仅在于描述语言。这正是 tldr 多语言维护模式的缩影：同一命令页在不同pages.*语言目录下各自翻译，但结构与语义保持一致。

二、别名背后的原命令：PowerShellGet-History

要真正用好h，就必须理解它指向的原命令。仓库中的 pages/windows/get-history.md 是Get-History的完整文档页，包含三条核心用法：

# Get-History > Display PowerShell command history. > Note: This command can only be used through PowerShell. - Display the commands history list with ID: `Get-History` - Get PowerShell history item by ID: `Get-History -Id {{item_id}}` - Display the last `n` commands: `Get-History -Count {{n}}`

由该文档可以确认三条事实：

1. Get-History用于显示 PowerShell 命令历史，即你在当前会话中执行过的命令列表；
2. 该命令只能通过 PowerShell 使用——也就是说，h作为其别名同样只能在 PowerShell 会话中生效，在传统的 Windows 命令提示符（cmd）中并没有意义；
3. 它支持-Id与-Count两个常用参数：前者按历史条目 ID 精确获取某一条记录，后者控制显示最近n条记录。

因此，在 PowerShell 中执行h与执行Get-History完全等价。当你想查看带 ID 的历史列表、按 ID 回溯某条命令、或只看最近若干条命令时，分别对应上面三个用法。

三、tldr 别名页（Alias Page）的设计规范

h这类「只是另一个命令的别名」的页面，在 tldr 中被称为别名页（Alias Page）。项目在 contributing-guides/style-guide.md 的 "Aliases" 小节中明确规定：当某个命令可以用别名调用时（例如vim可写作vi），可以创建别名页，把用户引导到原命令名上。

别名页的规范结构为：

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

而所有语言的别名页翻译模板统一维护在 contributing-guides/translation-templates/alias-pages.md 中。该文件收录了 en、ar、bg、bn、zh、zh_TW 等数十种语言的官方模板，其中保加利亚语（bg）模板为：

# example > Тази команда е псевдоним на `example`. - Виж документацията за оригиналната команда: `tldr example`

对照可见，pages.bg/windows/h.md 正是把模板中的三个example占位符分别替换为标题h、原命令Get-History与文档命令Get-History后得到的成品。换句话说，这份保加利亚语别名页不是手写拼凑的，而是完全按照官方 bg 模板生成的标准化页面。

值得一提的是，PowerShell 相关别名在 style-guide.md 中被划分为三类：替代既有cmd命令、仅存在于 PowerShell 的新别名、与其他程序产生冲突的别名。h/history属于仅在 PowerShell 中可用的别名，因此页面采用标准别名模板即可。

四、源码视角：别名页的生成与多语言同步机制

别名页的创建与同步并不是人工逐个翻译的，仓库提供了自动化脚本 scripts/set-alias-page.py。从源码结构看，其核心流程包含三个关键环节：

1. 模板占位符替换：generate_alias_page_content()函数（scripts/set-alias-page.py#L120-L142）接收语言模板和页面内容，按顺序把模板中的example占位符替换为页面标题、原命令名和文档命令名，从而生成完整的别名页 Markdown 内容。这与我们在第一节看到的页面结构完全吻合。

2. 别名页识别：get_alias_command_in_page()函数（scripts/set-alias-page.py#L221-L282）通过解析#标题行、> ...\command`描述行和 ``tldr ...` `` 行，从既有页面中提取标题、原命令与文档命令三项元数据，用于判断某页面是否为别名页。

3. 多语言同步：sync_alias_page_to_locale()（scripts/set-alias-page.py#L285-L304）遍历各pages.*语言目录，把英文别名页同步到对应语言；-l pt_BR之类的参数可限定只同步某个语言，-n为干跑（dry-run）模式，-s则把改动暂存到 Git。

脚本的实际用法示例如下（参考其 docstring）：

# 交互式创建一条别名页（如 osx/gsum） python3 scripts/set-alias-page.py -p osx/gsum # 将英文别名页同步到全部语言 python3 scripts/set-alias-page.py -S # 只同步巴西葡萄牙语，并暂存改动 python3 scripts/set-alias-page.py -S -l pt_BR -s

由此可见，pages.bg/windows/h.md 这类页面完全可以在英文别名页更新后，通过python3 scripts/set-alias-page.py -S批量同步到保加利亚语等所有语言目录，从而保证多语言文档始终与英文版一致。

五、别名页在实际使用中的跳转路径

对终端用户而言，别名页的价值在于「一句话指路」：看到h命令时，执行文档中给出的跳转命令即可直达原命令的完整用法：

# 查看 h 的别名页 tldr h # 跳转到原命令文档 tldr Get-History

此外，仓库中 pages/windows/history.md 同样是Get-History的别名页（内容结构相同），说明h与history都是 PowerShell 内建的Get-History别名，tldr 为它们分别维护了别名页，统一指向同一个原命令文档。

六、小结

从一份只有 6 行的保加利亚语文件 pages.bg/windows/h.md，可以完整梳理出 tldr 项目的一条关键设计链路：

• 命令层面：h是 PowerShellGet-History的别名，只能用于 PowerShell 会话，具备-Id、-Count等参数能力（见 pages/windows/get-history.md）；
• 文档层面：别名页遵循 contributing-guides/style-guide.md 的 Aliases 规范与 contributing-guides/translation-templates/alias-pages.md 的多语言模板；
• 工程层面：scripts/set-alias-page.py 通过占位符替换、别名识别与多语言同步，让数千个语言目录下的别名页能够低成本保持一致。

理解这条链路后，无论是阅读tldr h的输出，还是参与 tldr 多语言文档维护，都能快速定位「命令 → 模板 → 脚本」中任意一环，这也是本仓库协作式命令手册（Collaborative cheatsheets）高效运转的缩影。

• 文档
• 教程
• 知识库