pi-di18n

pi-di18n: full TUI i18n for pi (continues pi-i18n) plus summary localization (integrates pi-compaction-i18n)

Packages

Package details

extension

Install pi-di18n from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-di18n
Package
pi-di18n
Version
0.2.3
Published
Nov 14, 2026
Downloads
626/mo · 453/wk
Author
diwu507
License
MIT
Types
extension
Size
700.3 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "i18n": {
    "manifest": "./i18n.manifest.json",
    "capability": "pi.i18n.v1",
    "contractVersion": 1
  },
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-di18n

English | 简体中文 | 日本語 | 한국어

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-hacks to 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>.description bundle keys for all built-in slash commands, localized in every maintained locale.
  • Session selector translation — covers visible session-selector strings such as Resume 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 on replaces tool and parameter descriptions in provider request payloads so the model reads them in the active /lang locale.
  • Provider payload coverage — supports OpenAI-style, Anthropic, and Google/Gemini tool schemas:
    • OpenAI-style: tools[].function.description and function.parameters.properties.*.description
    • Anthropic: tools[].description and input_schema.properties.*.description
    • Google/Gemini: tools[].functionDeclarations[].description and parametersJsonSchema.properties.*.description
  • 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.json with English-source invalidation.
  • Summary localization — intercepts session_before_compact and session_before_tree so compaction and branch summaries follow the active /lang locale.
  • Extension i18n API compatibility — preserves pi-i18n/requestApi and pi-core/i18n/requestApi events for other extensions.

Installation

Once published:

pi install npm:pi-di18n

For local development:

pi install /absolute/path/to/pi-di18n

Then 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 --offline

Usage

Basic language setup:

/lang setup beginner
/lang zh-CN
/lang debug
/lang probe

Enable LLM-facing thinking localization:

/lang think on
/lang think doctor

Disable it:

/lang think off

Clear cached runtime translations:

/lang think clear      # clear current locale
/lang think clear-all  # clear all locales

Summary 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 on

The feature is off by default. When enabled, it uses a three-layer lookup:

  1. prefilled baseline translations shipped with the package;
  2. local cache with English-source invalidation;
  3. 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-run

Current verification commands:

npm test
npm pack --dry-run

Historical 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 probe

and also:

npm test
npm pack --dry-run

Changelog

See CHANGELOG.md for released versions and user-visible changes.

License

MIT