pi-extensions-i18n 0.2.0 → 0.3.0

package/README.md

@@ -1,42 +1,89 @@
 # pi-extensions-i18n
 
-Shared i18n runtime for pi extensions, with bilingual (zh-CN / en-US) support.
+Shared localization runtime for Pi extensions. It provides a small, catalog-backed API for `zh-CN`, `en-US`, and automatic locale selection.
 
-pi 扩展的公共中英文运行时。提供：
+## Why a shared package
 
-- `zh-CN`、`en-US` 和 `auto` 三种语言偏好；
-- 统一读取 `~/.pi/agent/extensions/pi-extensions-i18n/config.json`；
-- `/pi-language` 终端交互式语言配置命令；
-- `PI_EXTENSIONS_LOCALE` 环境变量覆盖配置；
-- 面向 UI、命令描述和 agent prompt 的翻译器，以及外部 JSON catalog 加载和校验。
+Independent Pi extensions still need the same operational pieces: a portable configuration path, locale precedence, fallback behavior, catalog validation, and parameter interpolation. Keeping those pieces here lets feature packages concentrate on their own behavior while keeping user-facing messages consistent.
 
-## Install / 安装
+## Features
+
+- `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.
+- Catalog loading and validation requiring both language entries for every message key.
+- Translator interpolation for user-facing UI, command descriptions, and agent prompts.
+
+## Install
 
 ```bash
 pi install npm:pi-extensions-i18n
 ```
 
-本包是共享 peer dependency，依赖它的扩展（如 `pi-distill`、`pi-tool-supervisor`）会自动引用，不会把配置复制到每个插件目录。
+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.
 
-## Locale priority / 语言优先级
+Reload Pi after installation:
 
 ```text
-PI_EXTENSIONS_LOCALE 环境变量 > 持久化配置 > 默认 zh-CN
+/reload
 ```
 
-`PI_EXTENSIONS_LOCALE` 和配置文件支持 `zh-CN`、`en-US`、`auto`，也接受 `zh`、`en` 简写。`auto` 根据 `LC_ALL`、`LC_MESSAGES` 或 `LANG` 判断系统语言。
+## Locale precedence
+
+```text
+PI_EXTENSIONS_LOCALE environment variable
+    > persisted config
+    > default zh-CN
+```
+
+The `auto` preference checks `LC_ALL`, `LC_MESSAGES`, and `LANG`; Chinese system locales resolve to `zh-CN`, and other locales resolve to `en-US`. `zh` and `en` are accepted as short aliases.
+
+Examples:
 
 ```bash
 PI_EXTENSIONS_LOCALE=en-US pi
 ```
 
-在 pi 中执行 `/pi-language` 可通过 select 菜单保存语言；也可以直接执行 `/pi-language en-US`。
+```text
+/pi-language en-US
+```
+
+## Extension author API
+
+The package exports the locale and catalog primitives used by the feature packages:
+
+```ts
+import {
+  createTranslator,
+  getLocale,
+  loadCatalog,
+} from "pi-extensions-i18n";
+
+const messages = loadCatalog(new URL("../locales/messages.json", import.meta.url));
+const i18n = createTranslator(messages);
+
+i18n.t("description");
+getLocale();
+```
+
+Catalog entries must contain both locale keys:
+
+```json
+{
+  "description": {
+    "zh-CN": "扩展描述",
+    "en-US": "Extension description"
+  }
+}
+```
 
-## Catalog layout / 翻译资源约定
+Invalid catalogs fail during loading, which makes missing translations visible in tests and CI instead of silently leaking a single-language message to users.
 
-扩展自己的翻译资源保留在对应包的 `locales/` 目录中，按源码模块拆分为 JSON 文件，例如 `pi-distill/locales/summary-utils.json`；本包自身的 `/pi-language` 文案位于 `locales/command.json`。
+## Requirements
 
-每个 catalog 条目必须同时包含 `zh-CN` 与 `en-US` 两个语言键（CI 强制检查）。运行时只共享语言解析、配置存储、catalog 校验和插值规则，避免各插件重复实现配置路径和 fallback。
+- Node.js 22 or newer.
+- Pi's extension runtime when using the `/pi-language` command.
 
 ## License
 

package/README.zh-CN.md

@@ -0,0 +1,90 @@
+# pi-extensions-i18n
+
+Pi 扩展公共国际化运行时。它提供基于 catalog 的小型 API，支持 `zh-CN`、`en-US` 和自动语言选择。
+
+## 为什么需要公共包
+
+独立的 Pi 扩展仍然需要相同的基础能力：可移植的配置路径、语言优先级、fallback、catalog 校验和参数插值。把这些能力集中在这里，功能包就可以专注于自身逻辑，同时保持用户可见文案的一致性。
+
+## 能力
+
+- 支持 `zh-CN`、`en-US` 和 `auto` 语言偏好。
+- 将设置持久化到 `~/.pi/agent/extensions/pi-extensions-i18n/config.json`。
+- 支持 `PI_EXTENSIONS_LOCALE` 环境变量覆盖。
+- 提供 `/pi-language` 交互式命令，也支持 `/pi-language en-US` 直接设置。
+- 加载并校验 catalog，要求每个消息 key 同时提供两种语言。
+- 为 UI、命令描述和 Agent prompt 提供用户文案插值。
+
+## 安装
+
+```bash
+pi install npm:pi-extensions-i18n
+```
+
+`pi-distill`、`pi-tool-supervisor` 等功能包会把它作为公共依赖使用。如果只需要语言命令，也可以单独安装本包。
+
+安装后重新加载 Pi：
+
+```text
+/reload
+```
+
+## 语言优先级
+
+```text
+PI_EXTENSIONS_LOCALE 环境变量
+    > 持久化配置
+    > 默认 zh-CN
+```
+
+选择 `auto` 时会检查 `LC_ALL`、`LC_MESSAGES` 和 `LANG`：中文系统语言解析为 `zh-CN`，其他语言解析为 `en-US`。同时接受 `zh` 和 `en` 简写。
+
+示例：
+
+```bash
+PI_EXTENSIONS_LOCALE=en-US pi
+```
+
+```text
+/pi-language en-US
+```
+
+## 扩展作者 API
+
+本包导出功能扩展使用的语言和 catalog 原语：
+
+```ts
+import {
+  createTranslator,
+  getLocale,
+  loadCatalog,
+} from "pi-extensions-i18n";
+
+const messages = loadCatalog(new URL("../locales/messages.json", import.meta.url));
+const i18n = createTranslator(messages);
+
+i18n.t("description");
+getLocale();
+```
+
+catalog 条目必须同时包含两种语言：
+
+```json
+{
+  "description": {
+    "zh-CN": "扩展描述",
+    "en-US": "Extension description"
+  }
+}
+```
+
+无效 catalog 会在加载阶段失败，让缺失翻译在测试和 CI 中暴露，而不是静默向用户泄露单一语言文案。
+
+## 要求
+
+- Node.js 22 或更高版本。
+- 使用 `/pi-language` 命令时需要 Pi 扩展运行时。
+
+## 许可证
+
+[MIT](../../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensions-i18n",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared i18n catalog loader & translator for pi extensions",
   "type": "module",
   "main": "./index.ts",
@@ -12,6 +12,7 @@
     "src",
     "locales",
     "README.md",
+    "README.zh-CN.md",
     "tsconfig.json"
   ],
   "scripts": {

package/src/index.ts

@@ -92,10 +92,12 @@ export function getLocalePreference(): LocalePreference {
     return DEFAULT_LOCALE_PREFERENCE;
   }
 
-  if (runtimePreference) return runtimePreference;
-  runtimePreference =
-    readPersistedPreference(resolveAgentDir()) ?? DEFAULT_LOCALE_PREFERENCE;
-  return runtimePreference;
+  const persisted = readPersistedPreference(resolveAgentDir());
+  if (persisted) {
+    runtimePreference = persisted;
+    return persisted;
+  }
+  return runtimePreference ?? DEFAULT_LOCALE_PREFERENCE;
 }
 
 function detectSystemLocale(): Locale {
@@ -174,9 +176,10 @@ export function createTranslator<Catalog extends MessageCatalog>(
       if (!entry) {
         throw new Error(`Unknown i18n message key: ${String(key)}`);
       }
-      const message = entry[getLocale()];
+      const locale = getLocale();
+      const message = entry[locale];
       if (message === undefined) {
-        throw new Error(`Missing ${getLocale()} translation for message key: ${String(key)}`);
+        throw new Error(`Missing ${locale} translation for message key: ${String(key)}`);
       }
       return interpolate(message, params);
     },