# pi-di18n

[English](./README.md) | [简体中文](./README-zh.md) | [日本語](./README-ja.md) | [한국어](./README-ko.md)

`pi-di18n` is the localization extension for [pi](https://github.com/earendil-works/pi-coding-agent). 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:

```bash
pi install npm:pi-di18n
```

For local development:

```bash
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:

```bash
pi -ne -e /absolute/path/to/pi-di18n/index.ts --offline
```

## Usage

Basic language setup:

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

Enable LLM-facing thinking localization:

```text
/lang think on
/lang think doctor
```

Disable it:

```text
/lang think off
```

Clear cached runtime translations:

```text
/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`:

```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.

```text
/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

```text
/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

```bash
npm install
npm test
npm pack --dry-run
```

Current verification commands:

```bash
npm test
npm pack --dry-run
```

Historical verification records and per-version adaptation logs live under [`doc/references/`](./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:

```text
/lang debug
/lang probe
```

and also:

```bash
npm test
npm pack --dry-run
```

## Changelog

See [`CHANGELOG.md`](./CHANGELOG.md) for released versions and user-visible changes.

## License

MIT
