中英文双语补全一键切换：PSCompletions 多语言支持完全指南

• CLI
• 开发工具

PSCompletions 是一款由 Rust 与 Lua 驱动的强大 Shell 命令补全器，支持 PowerShell、bash、zsh、fish 等主流 Shell。它内置了多语言支持（multilingual support），补全菜单的提示、用法说明和示例可以在中文（zh-CN）与英文（en-US）之间一键切换，让中文用户也能享受到全中文的补全体验。本文是一份完整指南，带你快速上手 PSCompletions 语言切换的所有操作。

为什么 PSCompletions 需要多语言支持？

补全菜单里最"劝退"的往往不是命令本身，而是一长串看不懂的英文提示。PSCompletions 把每个补全项的tip（提示）、usage（用法）、example（示例）都做了独立翻译，而不是简单机翻拼接。

以模块自身的psc补全为例，同一个add命令在两种语言下的提示完全不同：

示例说明也会被翻译，比如psc add git在中英文下的描述分别是"添加 git 补全"和"Add the git completion"。

一个补全的双语文件是怎么组织的？

每个补全都存放在独立的目录里，语言文件位于language/子目录中。以git为例，目录结构如下：

completions/git/ ├── config.json # 声明支持的语言列表 ├── hooks.lua # 动态补全逻辑（可选） └── language/ ├── en-US.json # 英文清单（单一事实来源） └── zh-CN.json # 中文翻译（结构相同，仅文案不同）

关键规则只有一条：两个语言文件的结构完全一致，只有tip/usage/example等文案字段被翻译。这样引擎在任意语言下都能安全地解析同一棵补全树，不会因翻译而"跑偏"。这一格式约定记录在 design/completion.md，机器可校验的格式定义则在 schema/ 目录下的 JSON Schema 中（中英文注释各一份）。

是否支持某语言，由config.json里的language字段声明，例如 completions/psc/config.json：

"language": ["en-US", "zh-CN"]

如果当前语言没有对应文件，会自动回退到声明列表中的第一个语言（通常是en-US），不会报错。

一键切换中英文：全局语言设置

切语言只需要一行命令：

# 切换为中文 psc config core language zh-CN # 切换回英文 psc config core language en-US

设置后立即生效，影响所有已添加的补全。用psc config core language（不带参数）可以随时查看当前语言。

💡 语言候选值本身也是可补全的：输入psc config core language <Tab>，菜单里就会列出en-US和zh-CN两个选项，鼠标点选即可。

PowerShell 用户的小福利：自动跟随系统语言

在 PowerShell 中，模块初始化时会根据$PSUICulture自动引导默认语言——如果你的 PowerShell 界面语言是中文，第一次触发补全时就会自动使用zh-CN，无需手动设置（详见 design/psc-cli.md 的语言默认值说明）。

bash / zsh / fish 用户则直接执行上面的psc config core language命令即可。

一个容易踩的坑：language 不能 --reset

与其他配置项不同，language不支持重置：

psc config core language --reset # ❌ 会被拒绝

这是有意的设计：语言没有"固定默认值"，它的初始值来自模块引导（如$PSUICulture），Rust 引擎的兜底值才是en-US。重置逻辑会跳过language键（design/psc-cli.md）。所以想换语言，直接设置目标值即可。

高级玩法：给某个补全单独指定语言

全局语言只是"基础层"。PSCompletions 支持按补全单独覆盖语言，优先级规则是：

单个补全的设置 > 全局语言 > 补全声明的第一个语言

比如你希望整体用中文，但docker保持英文（可能是团队约定），可以这样：

psc completion docker language en-US

查看某个补全当前的特殊配置（包含language）：

psc completion docker

单个配置项也可以重置回跟随全局：

psc completion docker language --reset

每个补全默认带有 4 个特殊配置：language/enable_tip/enable_tip_usage/enable_tip_example，完整示例可参考psc补全清单中的说明（completions/psc/language/zh-CN.json）。

语言切换后，已缓存的结果会怎样？

不用担心"切完语言菜单还是旧的"。引擎的结果缓存签名（cache signature）中包含了语言版本——同一份补全的en-US.json与zh-CN.json是不同的 manifest 文件，切换语言后缓存自动失效，下次 Tab 会立即按新语言重新渲染（design/menu.md）。

换句话说：切换即时生效，无需清缓存，无需重启 Shell。

常见问题 FAQ

Q1：切到中文后，某些补全还是英文？

两种可能：① 该补全没有提供zh-CN.json，自动回退到了声明的首语言；② 你曾用psc completion <name> language单独锁定过它的语言。执行psc completion <name>查看即可确认。

Q2：除了 en-US / zh-CN 还支持其他语言吗？

机制上语言码是开放的（例如types/psc.lua中对psc_localized的语言键做了补全提示），但内置补全库目前只提供en-US与zh-CN两种。

Q3：动态生成的提示（Lua hooks）也翻译吗？

会。Lua hooks 通过psc.add的本地化表按语言键提供译文，引擎按当前语言选择条目，找不到时回退en-US（design/hooks.md）。

总结：3 条命令玩转 PSCompletions 多语言

至此，你已掌握 PSCompletions 中英文双语补全的全部切换技巧：一条命令全局生效、按补全精细覆盖、缓存自动失效、即时刷新。配合内置补全库与动态排序，中文终端体验从此完整闭环 🚀

• CLI
• 开发工具