pi-di18n
v0.2.3
Published
pi-di18n: full TUI i18n for pi (continues pi-i18n) plus summary localization (integrates pi-compaction-i18n)
Maintainers
Readme
pi-di18n
pi-di18n is the localization extension for pi. It continues the full TUI i18n and core-hacks line from pi-i18n, integrates summary localization from pi-compaction-i18n, and adds LLM-facing tool-description localization through /lang think.
What It Localizes
pi-di18n has three localization lines:
| Line | Audience | Scope |
|------|----------|-------|
| A-line: TUI localization | Human user | Buttons, selectors, status/warning/error messages, slash-command descriptions, session selector text |
| B-line: thinking localization | LLM | Tool and parameter description strings sent in provider payloads |
| C-line: summary localization | Human user | /compact and /tree summaries |
Features
- Full TUI localization — keeps
core-hacksto runtime-patch pi internal render paths, covering UI labels, selectors, status messages, and built-in slash-command descriptions. - Slash-command description fix — ships
pi.slash.<name>.descriptionbundle keys for all built-in slash commands, localized in every maintained locale. - Session selector translation — covers visible
session-selectorstrings such asResume Session,Threaded,Recent,Fuzzy, and delete prompts. - Non-invasive status bar — does not replace pi's native footer/status bar, so model, cwd, token, git, and worktree information remain visible.
- Runtime UI description localization — asynchronously localizes extension, prompt-template, and skill command descriptions for autocomplete UI, then caches them locally without blocking rendering.
- LLM thinking-language localization —
/lang think onreplaces tool and parameter descriptions in provider request payloads so the model reads them in the active/langlocale. - Provider payload coverage — supports OpenAI-style, Anthropic, and Google/Gemini tool schemas:
- OpenAI-style:
tools[].function.descriptionandfunction.parameters.properties.*.description - Anthropic:
tools[].descriptionandinput_schema.properties.*.description - Google/Gemini:
tools[].functionDeclarations[].descriptionandparametersJsonSchema.properties.*.description
- OpenAI-style:
- Prefilled baseline translations — includes offline baseline translations for 12 languages:
zh-CN,zh-TW,ja,ko,ru,vi,es,pt-BR,de,fr,id,hi. - Runtime fallback and cache — descriptions missing from the baseline are translated with the current session model and cached under
~/.pi/agent/state/pi-di18n/think.jsonwith English-source invalidation. - Summary localization — intercepts
session_before_compactandsession_before_treeso compaction and branch summaries follow the active/langlocale. - Extension i18n API compatibility — preserves
pi-i18n/requestApiandpi-core/i18n/requestApievents for other extensions.
Installation
Once published:
pi install npm:pi-di18nFor local development:
pi install /absolute/path/to/pi-di18nThen restart pi. /reload reloads extension resources, but after editing core-hacks you must restart pi because its monkeypatches remain in the current process.
To test this checkout without loading installed extensions:
pi -ne -e /absolute/path/to/pi-di18n/index.ts --offlineUsage
Basic language setup:
/lang setup beginner
/lang zh-CN
/lang debug
/lang probeEnable LLM-facing thinking localization:
/lang think on
/lang think doctorDisable it:
/lang think offClear cached runtime translations:
/lang think clear # clear current locale
/lang think clear-all # clear all localesSummary localization needs no extra command. It runs automatically when /compact or /tree branch summaries are triggered, and follows the current /lang locale.
Coexisting with tool override extensions
Pi allows an extension to replace a built-in tool, but rejects two extensions that register the same tool name. If another extension owns one of pi-di18n's localized built-in tool overrides, reserve that name in ~/.pi/agent/state/pi-di18n/config.json or the project-local .pi/state/pi-di18n/config.json:
{
"locale": "zh-CN",
"fallbackLocale": "en",
"disabledBuiltinToolOverrides": ["read", "edit"]
}Allowed values are read, bash, edit, and write; unknown values are ignored. Only the listed localized tool renderers are skipped. TUI localization, summary localization, /lang think, i18n_get_locale, and the remaining built-in tool renderers stay enabled. Reload or restart Pi after changing this extension-load setting.
The localized bash override reads Pi's effective shellPath and shellCommandPrefix for each call through the host settings API when available. Older Pi versions use saved settings for the call's current working directory and project trust. This keeps custom shells and command prefixes active after localization.
OpenAI Responses compaction compatibility
If summary generation reports Unsupported parameter: prompt_cache_options, verify the selected model's compat.supportsExplicitPromptCacheMode metadata against the configured endpoint. Pi's provider adapter emits that field for no-cache summary requests when this flag is true. For an endpoint that rejects the field, set the flag to false in the model configuration and reload its metadata. This omits the unsupported field; the endpoint may still apply implicit caching. pi-di18n continues to use separate summary routing IDs and does not reuse the conversation's cache key.
/lang think Behavior
/lang think does not set a separate language. It follows the current /lang locale.
/lang zh-CN
/lang think onThe feature is off by default. When enabled, it uses a three-layer lookup:
- prefilled baseline translations shipped with the package;
- local cache with English-source invalidation;
- runtime LLM fallback using the current session model.
Safety boundary: only prose description strings are translated. Tool names, parameter names, type, enum, defaults, values, and schema structure are never translated.
Diagnostics
/lang debug
/lang probe
/lang think doctor/lang think doctor reports:
- current locale and enabled state;
- session tool/parameter counts;
- baseline coverage;
- cache counts;
- stale entries whose English source changed;
- pending descriptions that still need runtime translation.
Development
npm install
npm test
npm pack --dry-runCurrent verification commands:
npm test
npm pack --dry-runHistorical verification records and per-version adaptation logs live under doc/references/.
Directory Layout
| Path | Description |
|------|-------------|
| index.ts | Extension entry point; registers /lang, core-hacks, thinking localization, and summary-localization hooks |
| src/core-hacks.ts | Runtime patches for TUI localization |
| src/pi-ui.ts | Localization for tool rendering, buttons, and other UI surfaces |
| src/compaction/ | Localization for /compact and /tree summaries |
| src/think/ | B-line LLM thinking-language localization |
| src/ui-localize/ | A-line runtime UI description localization for extension/prompt/skill autocomplete descriptions |
| src/think-locales/ | Prefilled baseline translations: en source + 12 target languages |
| scripts/ | Maintenance scripts for exporting and refreshing generated baseline sources |
| scripts/export-think-baseline.mjs | Export pi built-in tool descriptions as baseline source; re-run on pi upgrade |
| locales/ | i18n bundles |
| src/core-hacks-locales/ | Exact/substring translation packs for core-hacks |
| tests/ | vitest regression tests |
| PLAN.md | Current execution status and resume point (single source of truth) |
| doc/架构/ | Current mechanism: architecture, three-line data flow, patch boundaries |
| doc/规格/ | Dictionary-pack key contracts (the project's spec) |
| doc/references/ | Evidence, verification records, and archived per-version adaptation logs |
| doc/决策档案/ | ADRs (hard-to-reverse decisions) |
| doc/术语表.md, doc/经验笔记.md | Glossary; practices and pitfalls |
| .artifacts/ | Local raw evidence (screenshots, captures); Git-ignored, not distributed |
Compatibility
The baseline target is @earendil-works/pi-coding-agent 1.5.x. Earlier baselines (0.83.x, 1.1.0) are still supported: the runtime patches resolve the bundle layout Pi ships since 1.1.0 and fall back to the plain dist/ modules for older builds.
pi currently has no native full TUI i18n API. TUI localization therefore depends on best-effort core-hacks that patch pi internal render paths. After every pi upgrade, run:
/lang debug
/lang probeand also:
npm test
npm pack --dry-runChangelog
See CHANGELOG.md for released versions and user-visible changes.
License
MIT
