pi-extensions-i18n 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# pi-extensions-i18n
+
+Shared i18n runtime for pi extensions, with bilingual (zh-CN / en-US) support.
+
+pi 扩展的公共中英文运行时。提供：
+
+- `zh-CN`、`en-US` 和 `auto` 三种语言偏好；
+- 统一读取 `~/.pi/agent/extensions/pi-extensions-i18n/config.json`；
+- `/pi-language` 终端交互式语言配置命令；
+- `PI_EXTENSIONS_LOCALE` 环境变量覆盖配置；
+- 面向 UI、命令描述和 agent prompt 的翻译器，以及外部 JSON catalog 加载和校验。
+
+## Install / 安装
+
+```bash
+pi install npm:pi-extensions-i18n
+```
+
+本包是共享 peer dependency，依赖它的扩展（如 `pi-distill`、`pi-tool-supervisor`）会自动引用，不会把配置复制到每个插件目录。
+
+## Locale priority / 语言优先级
+
+```text
+PI_EXTENSIONS_LOCALE 环境变量 > 持久化配置 > 默认 zh-CN
+```
+
+`PI_EXTENSIONS_LOCALE` 和配置文件支持 `zh-CN`、`en-US`、`auto`，也接受 `zh`、`en` 简写。`auto` 根据 `LC_ALL`、`LC_MESSAGES` 或 `LANG` 判断系统语言。
+
+```bash
+PI_EXTENSIONS_LOCALE=en-US pi
+```
+
+在 pi 中执行 `/pi-language` 可通过 select 菜单保存语言；也可以直接执行 `/pi-language en-US`。
+
+## Catalog layout / 翻译资源约定
+
+扩展自己的翻译资源保留在对应包的 `locales/` 目录中，按源码模块拆分为 JSON 文件，例如 `pi-distill/locales/summary-utils.json`；本包自身的 `/pi-language` 文案位于 `locales/command.json`。
+
+每个 catalog 条目必须同时包含 `zh-CN` 与 `en-US` 两个语言键（CI 强制检查）。运行时只共享语言解析、配置存储、catalog 校验和插值规则，避免各插件重复实现配置路径和 fallback。
+
+## License
+
+[MIT](../../LICENSE)

package/index.ts

@@ -0,0 +1,2 @@
+export { default } from "./src/index.ts";
+export * from "./src/index.ts";

package/locales/command.json

@@ -0,0 +1,42 @@
+{
+  "description": {
+    "zh-CN": "配置 PiExtensions 的界面和 prompt 语言",
+    "en-US": "Configure the PiExtensions UI and prompt language"
+  },
+  "noUi": {
+    "zh-CN": "语言配置需要在带 UI 的 Pi 会话中运行。",
+    "en-US": "Language settings require a Pi session with a UI."
+  },
+  "title": {
+    "zh-CN": "PiExtensions 语言",
+    "en-US": "PiExtensions language"
+  },
+  "zh": {
+    "zh-CN": "简体中文 (zh-CN)",
+    "en-US": "Simplified Chinese (zh-CN)"
+  },
+  "en": {
+    "zh-CN": "English (en-US)",
+    "en-US": "English (en-US)"
+  },
+  "auto": {
+    "zh-CN": "跟随系统语言 (auto)",
+    "en-US": "Follow system language (auto)"
+  },
+  "saved": {
+    "zh-CN": "语言已保存为 {locale}，新的 UI 和 prompt 将使用该语言。",
+    "en-US": "Language saved as {locale}; new UI and prompts will use this language."
+  },
+  "invalid": {
+    "zh-CN": "不支持的语言设置：{value}。请选择 zh-CN、en-US 或 auto。",
+    "en-US": "Unsupported language setting: {value}. Choose zh-CN, en-US, or auto."
+  },
+  "failed": {
+    "zh-CN": "保存语言设置失败：{error}",
+    "en-US": "Failed to save language settings: {error}"
+  },
+  "envOverride": {
+    "zh-CN": "当前由 {env} 环境变量覆盖，持久化值将在移除环境变量后生效。",
+    "en-US": "The {env} environment variable currently overrides this value; the persisted setting will apply after it is removed."
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "pi-extensions-i18n",
+  "version": "0.1.0",
+  "description": "Shared i18n catalog loader & translator for pi extensions",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "locales",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/pi-i18n.test.ts",
+    "typecheck": "tsc --noEmit --pretty false",
+    "build": "npm run typecheck",
+    "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "maplezzk",
+  "homepage": "https://github.com/maplezzk/pi-extensions/tree/main/packages/pi-extensions-i18n",
+  "bugs": "https://github.com/maplezzk/pi-extensions/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maplezzk/pi-extensions.git",
+    "directory": "packages/pi-extensions-i18n"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "i18n",
+    "coding-agent"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@types/node": "24.12.4",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,251 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+export const SUPPORTED_LOCALES = ["zh-CN", "en-US"] as const;
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+export type LocalePreference = Locale | "auto";
+
+export const DEFAULT_LOCALE_PREFERENCE: LocalePreference = "zh-CN";
+export const LOCALE_ENV = "PI_EXTENSIONS_LOCALE";
+export const LOCALE_CONFIG_FILE = "config.json";
+export const LOCALE_CONFIG_DIR = "extensions/pi-extensions-i18n";
+
+export interface LocaleConfig {
+  locale: LocalePreference;
+}
+
+export type MessageCatalog = Record<string, Record<Locale, string>>;
+export type MessageKey<Catalog extends MessageCatalog> = keyof Catalog & string;
+export type MessageParams = Record<string, string | number>;
+
+interface Translator<Catalog extends MessageCatalog> {
+  locale(): Locale;
+  t(key: MessageKey<Catalog>, params?: MessageParams): string;
+}
+
+let runtimePreference: LocalePreference | undefined;
+
+function normalizeLocale(value: unknown): LocalePreference | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "auto") return "auto";
+  if (normalized === "zh" || normalized === "zh-cn") return "zh-CN";
+  if (normalized === "en" || normalized === "en-us") return "en-US";
+  return undefined;
+}
+
+export function parseLocalePreference(value: string): LocalePreference | undefined {
+  return normalizeLocale(value);
+}
+
+function resolveAgentDir(): string {
+  const configured = process.env.PI_CODING_AGENT_DIR;
+  if (!configured) return join(homedir(), ".pi", "agent");
+  if (configured === "~") return homedir();
+  return configured.startsWith("~/")
+    ? join(homedir(), configured.slice(2))
+    : configured;
+}
+
+export function getLocaleConfigPath(agentDir = resolveAgentDir()): string {
+  return join(agentDir, LOCALE_CONFIG_DIR, LOCALE_CONFIG_FILE);
+}
+
+function readPersistedPreference(agentDir: string): LocalePreference | undefined {
+  const configPath = getLocaleConfigPath(agentDir);
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    const value = normalizeLocale(
+      typeof parsed === "object" && parsed !== null
+        ? (parsed as Record<string, unknown>).locale
+        : undefined,
+    );
+    if (value) return value;
+    console.warn(
+      `[pi-extensions-i18n] Invalid locale in ${configPath}; using ${DEFAULT_LOCALE_PREFERENCE}.`,
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      console.warn(
+        `[pi-extensions-i18n] Failed to read ${configPath}; using ${DEFAULT_LOCALE_PREFERENCE}: ${String(error)}`,
+      );
+    }
+  }
+  return undefined;
+}
+
+export function getLocalePreference(): LocalePreference {
+  const envValue = process.env[LOCALE_ENV];
+  if (envValue !== undefined) {
+    const parsed = normalizeLocale(envValue);
+    if (parsed) return parsed;
+    console.warn(
+      `[pi-extensions-i18n] Invalid ${LOCALE_ENV}=${JSON.stringify(envValue)}; using ${DEFAULT_LOCALE_PREFERENCE}.`,
+    );
+    return DEFAULT_LOCALE_PREFERENCE;
+  }
+
+  if (runtimePreference) return runtimePreference;
+  runtimePreference =
+    readPersistedPreference(resolveAgentDir()) ?? DEFAULT_LOCALE_PREFERENCE;
+  return runtimePreference;
+}
+
+function detectSystemLocale(): Locale {
+  const systemLocale = process.env.LC_ALL ?? process.env.LC_MESSAGES ?? process.env.LANG ?? "";
+  return systemLocale.toLowerCase().startsWith("zh") ? "zh-CN" : "en-US";
+}
+
+export function getLocale(): Locale {
+  const preference = getLocalePreference();
+  return preference === "auto" ? detectSystemLocale() : preference;
+}
+
+export function resetLocaleState(): void {
+  runtimePreference = undefined;
+}
+
+export function saveLocalePreference(
+  preference: LocalePreference,
+  agentDir = resolveAgentDir(),
+): string {
+  const normalized = normalizeLocale(preference);
+  if (!normalized) {
+    throw new Error(`Unsupported locale preference: ${String(preference)}`);
+  }
+
+  const configPath = getLocaleConfigPath(agentDir);
+  mkdirSync(dirname(configPath), { recursive: true });
+  const config: LocaleConfig = { locale: normalized };
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  runtimePreference = normalized;
+  return configPath;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function loadCatalog(catalogFile: URL | string): MessageCatalog {
+  const filePath = catalogFile instanceof URL ? fileURLToPath(catalogFile) : catalogFile;
+  const parsed: unknown = JSON.parse(readFileSync(filePath, "utf8"));
+  if (!isRecord(parsed)) {
+    throw new Error(`Invalid i18n catalog: expected an object in ${filePath}`);
+  }
+
+  const catalog: MessageCatalog = {};
+  for (const [key, entry] of Object.entries(parsed)) {
+    if (!isRecord(entry) || typeof entry["zh-CN"] !== "string" || typeof entry["en-US"] !== "string") {
+      throw new Error(`Invalid i18n catalog entry ${key} in ${filePath}`);
+    }
+    catalog[key] = {
+      "zh-CN": entry["zh-CN"],
+      "en-US": entry["en-US"],
+    };
+  }
+  return catalog;
+}
+
+function interpolate(template: string, params: MessageParams | undefined): string {
+  if (!params) return template;
+  return template.replace(/\{([A-Za-z0-9_]+)\}/g, (placeholder, name) => {
+    const value = params[name];
+    if (value === undefined) {
+      throw new Error(`Missing interpolation value for ${placeholder}`);
+    }
+    return String(value);
+  });
+}
+
+export function createTranslator<Catalog extends MessageCatalog>(
+  catalog: Catalog,
+): Translator<Catalog> {
+  return {
+    locale: getLocale,
+    t(key, params) {
+      const entry = catalog[key];
+      if (!entry) {
+        throw new Error(`Unknown i18n message key: ${String(key)}`);
+      }
+      const message = entry[getLocale()];
+      if (message === undefined) {
+        throw new Error(`Missing ${getLocale()} translation for message key: ${String(key)}`);
+      }
+      return interpolate(message, params);
+    },
+  };
+}
+
+const commandMessages = loadCatalog(
+  new URL("../locales/command.json", import.meta.url),
+);
+
+function registerLocaleCommand(pi: ExtensionAPI): void {
+  const i18n = createTranslator(commandMessages);
+  pi.registerCommand("pi-language", {
+    description: i18n.t("description"),
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify(i18n.t("noUi"), "warning");
+        return;
+      }
+
+      const requested = args.trim();
+      const directPreference = requested ? parseLocalePreference(requested) : undefined;
+      if (requested && !directPreference) {
+        ctx.ui.notify(i18n.t("invalid", { value: requested }), "error");
+        return;
+      }
+
+      let preference = directPreference;
+      if (!preference) {
+        const options = [
+          i18n.t("zh"),
+          i18n.t("en"),
+          i18n.t("auto"),
+        ];
+        const current = getLocalePreference();
+        const currentOption = current === "zh-CN"
+          ? options[0]
+          : current === "en-US"
+            ? options[1]
+            : options[2];
+        const selected = await ctx.ui.select(
+          `${i18n.t("title")} [${currentOption}]`,
+          options,
+        );
+        if (selected === undefined) return;
+        preference = selected === options[0]
+          ? "zh-CN"
+          : selected === options[1]
+            ? "en-US"
+            : "auto";
+      }
+
+      try {
+        const configPath = saveLocalePreference(preference);
+        const envOverride = process.env[LOCALE_ENV];
+        const overrideNotice = envOverride
+          ? `\n${i18n.t("envOverride", { env: LOCALE_ENV })}`
+          : "";
+        ctx.ui.notify(
+          `${i18n.t("saved", { locale: preference })}${overrideNotice}\n${configPath}`,
+          "info",
+        );
+      } catch (error) {
+        ctx.ui.notify(i18n.t("failed", { error: String(error) }), "error");
+      }
+    },
+  });
+}
+
+export default function piI18n(pi: ExtensionAPI): void {
+  registerLocaleCommand(pi);
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["index.ts", "src/**/*.ts"]
+}