pi-i18n

LTR-only i18n/l10n platform for the Pi coding agent TUI and for Pi extensions.

Why it’s different:

• extension-only: no pi-core fork required
• ships real locale bundles + a small API for other extensions
• includes opt-in core-hacks (runtime patching) to localize high-impact Pi UI surfaces today

If this is useful, please star the repo → it directly influences how much time goes into expanding locale coverage.

What it looks like

Deterministic “immersive tour” demo (all locales, 3 phases):

1. /settings across all locales
2. simulated localized chat across all locales
3. /hotkeys across all locales

Install

Install with Pi, not npm:

pi install npm:pi-i18n

Then restart Pi (or run /reload).

Quickstart (2 minutes)

1. Apply the beginner preset:

/lang setup beginner

2. Switch language (examples):

/lang zh-TW
/lang ja
/lang fr

3. Health checks:

/lang doctor
/lang debug
/lang probe

Commands

All operational controls stay under /lang (command names are not localized):

• /lang — switch UI language / pick a locale
• /lang doctor — check missing keys / placeholder mismatches
• /lang debug — diagnostics for core-hacks + slash menu surfaces
• /lang probe [on|off|reset] — runtime patch probe mode/report
• /lang setup beginner — sane defaults + enables core-hacks
• /lang demo chat — deterministic localized demo chat
• /lang hacks — toggle core-hacks

Locale coverage

• Full bundles: en, zh-TW, zh-CN, ja, ko, es, pt-BR, fr, de
• Stub (English) bundles: it, pt-PT, nl, pl, tr, vi, id, uk, hi, sv, da, fi, cs, ro, el, sg
• RTL: not supported in v1 (explicitly out of scope)

What the extension actually does

1) i18n platform for extensions

• bundles (BundleV1) + namespace/key translation API
• compatibility surface:
  • pi-i18n/requestApi
  • pi-i18n/registerBundle
• upstream-aligned aliases (pi-core/i18n/*) so future core i18n can replace this cleanly

2) Best-effort Pi UI localization (no pi-core changes)

Pi UI strings are not all routed through an i18n system today. So this project includes core-hacks: runtime monkeypatching against internal Pi UI render paths.

Scope is intentionally conservative:

• UI chrome / selectors / status / warnings / errors
• slash command descriptions and help surfaces (e.g. /hotkeys)
• never tool args/results, never model output

Implementation anchor:

• src/core-hacks.ts

For extension authors

Request the API synchronously and translate at render time:

let i18n: any = null;
pi.events.emit("pi-i18n/requestApi", {
  reply: (api: any) => {
    i18n = api;
  },
});

const t = (k: string, p?: any) => (i18n ? i18n.t(`ext.myext.${k}`, p) : k);

Register bundles:

pi.events.emit("pi-i18n/registerBundle", bundle);

Contract + rollout standards:

• SPEC.md

Configuration

Config is stored as JSON.

User config:

• ~/.pi/agent/state/pi-i18n/config.json

Project override:

• <repo>/.pi/state/pi-i18n/config.json

Common keys:

• locale (e.g. "zh-TW", "fr")
• fallbackLocale (default: "en")
• coreHacksEnabled (best-effort UI localization)
• probeEnabled (patch telemetry)
• disableHeader, disableHeaderOnStartup

Files

• user config: ~/.pi/agent/state/pi-i18n/config.json
• project config: <repo>/.pi/state/pi-i18n/config.json

Troubleshooting

• Installed but /lang is unknown
  • run /reload (or restart Pi)
• Strings didn’t change after switching locale
  • run /lang hacks (core-hacks must be enabled to localize non-i18n’d Pi UI)
• Unsure what’s patched
  • run /lang probe and /lang debug

Development

Local dev install:

pi install -l <path-to-pi-i18n>

Then:

/reload
/lang doctor

For maintainers

Release plan: see RELEASE.md.

Manual quality gate (in a real Pi session):

/lang setup beginner
/lang doctor
/lang debug
/lang probe

/settings
/hotkeys

Demo media (how to regenerate the GIF)

The hero GIF is produced via stills → stitch (not fragile sleeps):

# WSL2 recommended
OUT="$HOME/tmp/pi-i18n-immersive-$(date +%F)-r1"
mkdir -p "$OUT"
bash tools/vhs/make-immersive-stills.sh "$OUT"

# outputs:
# - $OUT/pi-immersive.gif
# - $OUT/pi-immersive.mp4
# - $OUT/stills/*.png

See VHS.md for WSL setup (ttyd >= 1.7.2).

License

MIT