pi-extensions-i18n 0.3.0 → 0.4.0

package/README.md

@@ -11,7 +11,7 @@ Independent Pi extensions still need the same operational pieces: a portable con
 - `zh-CN`, `en-US`, and `auto` locale preferences.
 - Persistent setting at `~/.pi/agent/extensions/pi-extensions-i18n/config.json`.
 - `PI_EXTENSIONS_LOCALE` environment-variable override.
-- `/pi-language` interactive command, plus `/pi-language en-US` direct selection.
+- `/config:language` interactive command, plus `/config:language en-US` direct selection.
 - Catalog loading and validation requiring both language entries for every message key.
 - Translator interpolation for user-facing UI, command descriptions, and agent prompts.
 
@@ -21,7 +21,7 @@ Independent Pi extensions still need the same operational pieces: a portable con
 pi install npm:pi-extensions-i18n
 ```
 
-Feature packages such as `pi-distill` and `pi-tool-supervisor` use it as a shared dependency. Install it explicitly when you want the locale command by itself.
+Feature packages use it as a shared dependency and load its extension entry automatically, so installing a feature package is enough to provide the locale command. Install this package directly only when you want the locale command without another feature package.
 
 Reload Pi after installation:
 
@@ -46,7 +46,7 @@ PI_EXTENSIONS_LOCALE=en-US pi
 ```
 
 ```text
-/pi-language en-US
+/config:language en-US
 ```
 
 ## Extension author API
@@ -83,7 +83,7 @@ Invalid catalogs fail during loading, which makes missing translations visible i
 ## Requirements
 
 - Node.js 22 or newer.
-- Pi's extension runtime when using the `/pi-language` command.
+- Pi's extension runtime when using the `/config:language` command. `/pi-language` remains available as a compatibility alias.
 
 ## License
 

package/README.zh-CN.md

@@ -11,7 +11,7 @@ Pi 扩展公共国际化运行时。它提供基于 catalog 的小型 API，支
 - 支持 `zh-CN`、`en-US` 和 `auto` 语言偏好。
 - 将设置持久化到 `~/.pi/agent/extensions/pi-extensions-i18n/config.json`。
 - 支持 `PI_EXTENSIONS_LOCALE` 环境变量覆盖。
-- 提供 `/pi-language` 交互式命令，也支持 `/pi-language en-US` 直接设置。
+- 提供 `/config:language` 交互式命令，也支持 `/config:language en-US` 直接设置。
 - 加载并校验 catalog，要求每个消息 key 同时提供两种语言。
 - 为 UI、命令描述和 Agent prompt 提供用户文案插值。
 
@@ -21,7 +21,7 @@ Pi 扩展公共国际化运行时。它提供基于 catalog 的小型 API，支
 pi install npm:pi-extensions-i18n
 ```
 
-`pi-distill`、`pi-tool-supervisor` 等功能包会把它作为公共依赖使用。如果只需要语言命令，也可以单独安装本包。
+各功能包会自动安装并加载这个公共依赖，因此安装任意使用它的功能包即可使用语言命令。只有不安装其他功能包、想单独使用语言命令时，才需要直接安装本包。
 
 安装后重新加载 Pi：
 
@@ -46,7 +46,7 @@ PI_EXTENSIONS_LOCALE=en-US pi
 ```
 
 ```text
-/pi-language en-US
+/config:language en-US
 ```
 
 ## 扩展作者 API
@@ -83,7 +83,7 @@ catalog 条目必须同时包含两种语言：
 ## 要求
 
 - Node.js 22 或更高版本。
-- 使用 `/pi-language` 命令时需要 Pi 扩展运行时。
+- 使用 `/config:language` 命令时需要 Pi 扩展运行时；`/pi-language` 仍作为兼容别名保留。
 
 ## 许可证
 

package/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: configure-pi-extensions-i18n
+description: "配置 Pi 扩展共享语言并排查 locale 优先级、持久化设置和 catalog。Use when changing zh-CN/en-US/auto language behavior."
+---
+
+# 配置 pi-extensions-i18n
+
+## 修改语言
+
+优先使用 `/config:language zh-CN|en-US|auto`；不带参数时使用交互界面。设置持久化到实际 Pi agent 目录的 `extensions/pi-extensions-i18n/config.json`。
+
+语言优先级：
+
+1. `PI_EXTENSIONS_LOCALE`；
+2. 持久化配置；
+3. 默认 `zh-CN`。
+
+`auto` 根据 `LC_ALL`、`LC_MESSAGES`、`LANG` 选择中文或英文。`/pi-language` 只是兼容别名。
+
+## 验证
+
+执行语言命令后观察下一个使用共享 i18n 的扩展文案。若环境变量存在，它会覆盖持久化值；必须先报告这个覆盖关系，不能反复改 JSON。修改 catalog 时，每个 key 必须同时有 `zh-CN` 与 `en-US`，缺失翻译应作为加载错误修复，不能静默 fallback。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensions-i18n",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared i18n catalog loader & translator for pi extensions",
   "type": "module",
   "main": "./index.ts",
@@ -13,6 +13,7 @@
     "locales",
     "README.md",
     "README.zh-CN.md",
+    "SKILL.md",
     "tsconfig.json"
   ],
   "scripts": {
@@ -24,6 +25,9 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
     ]
   },
   "engines": {

package/src/index.ts

@@ -192,7 +192,7 @@ const commandMessages = loadCatalog(
 
 function registerLocaleCommand(pi: ExtensionAPI): void {
   const i18n = createTranslator(commandMessages);
-  pi.registerCommand("pi-language", {
+  const command = {
     description: i18n.t("description"),
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       if (!ctx.hasUI) {
@@ -246,7 +246,10 @@ function registerLocaleCommand(pi: ExtensionAPI): void {
         ctx.ui.notify(i18n.t("failed", { error: String(error) }), "error");
       }
     },
-  });
+  };
+  for (const name of ["config:language", "pi-language"] as const) {
+    pi.registerCommand(name, command);
+  }
 }
 
 export default function piI18n(pi: ExtensionAPI): void {