pi-extensions-i18n

Shared localization runtime for Pi extensions. It provides a small, catalog-backed API for zh-CN, en-US, and automatic locale selection.

Why a shared package

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.

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.
• /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.

Install

pi install npm:pi-extensions-i18n

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:

/reload

Locale precedence

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:

PI_EXTENSIONS_LOCALE=en-US pi

/config:language en-US

Extension author API

The package exports the locale and catalog primitives used by the feature packages:

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:

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

Invalid catalogs fail during loading, which makes missing translations visible in tests and CI instead of silently leaking a single-language message to users.

Requirements

• Node.js 22 or newer.
• Pi's extension runtime when using the /config:language command. /pi-language remains available as a compatibility alias.

License

MIT