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 环境变量覆盖。
• 提供 /config:language 交互式命令，也支持 /config:language en-US 直接设置。
• 加载并校验 catalog，要求每个消息 key 同时提供两种语言。
• 为 UI、命令描述和 Agent prompt 提供用户文案插值。

安装

pi install npm:pi-extensions-i18n

各功能包会自动安装并加载这个公共依赖，因此安装任意使用它的功能包即可使用语言命令。只有不安装其他功能包、想单独使用语言命令时，才需要直接安装本包。

安装后重新加载 Pi：

/reload

语言优先级

PI_EXTENSIONS_LOCALE 环境变量
    > 持久化配置
    > 默认 zh-CN

选择 auto 时会检查 LC_ALL、LC_MESSAGES 和 LANG：中文系统语言解析为 zh-CN，其他语言解析为 en-US。同时接受 zh 和 en 简写。

示例：

PI_EXTENSIONS_LOCALE=en-US pi

/config:language en-US

扩展作者 API

本包导出功能扩展使用的语言和 catalog 原语：

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 条目必须同时包含两种语言：

{
  "description": {
    "zh-CN": "扩展描述",
    "en-US": "Extension description"
  }
}

无效 catalog 会在加载阶段失败，让缺失翻译在测试和 CI 中暴露，而不是静默向用户泄露单一语言文案。

要求

• Node.js 22 或更高版本。
• 使用 /config:language 命令时需要 Pi 扩展运行时；/pi-language 仍作为兼容别名保留。

许可证

MIT