pi-web-i18n

UI language pack for jmfederico/pi-web
面向 jmfederico/pi-web 的界面语言包

| 中文 | English | |------|---------| | ↓ 中文说明 | ↓ English |

| | | |---|---| | Plugin id / 插件 id | i18n | | Default locale / 默认语言 | zh-CN（简体中文） | | Also ships / 另附 | en（原文）、ja（起步） | | Switch UI / 切换入口 | Actions → Language…（Ctrl+Shift+L / Cmd+Shift+L） | | Storage / 存储键 | localStorage["pi-web-i18n-locale"] | | npm | | | GitHub | |

Official docs / 官方文档: pi-web.dev/plugins · plugins.md

中文

PI WEB 没有官方 i18n API。本插件用 英文原文 → 译文 词典，在开放的 Shadow DOM 里改写文本与常见属性（title / aria-label / placeholder / alt），实现界面多语言。

安装（本地插件 · 推荐）

PI WEB 从 ~/.pi-web/plugins/<id>/ 加载本地插件（若设置了 PI_WEB_DATA_DIR 则用 $PI_WEB_DATA_DIR/plugins）。无需重建 PI WEB，也不必重启 sessiond。

方式 A — 直接克隆到插件目录

Linux / macOS / Git Bash

mkdir -p ~/.pi-web/plugins
git clone https://github.com/imHansiy/pi-web-i18n.git ~/.pi-web/plugins/i18n

Windows（PowerShell）

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.pi-web\plugins" | Out-Null
git clone https://github.com/imHansiy/pi-web-i18n.git "$env:USERPROFILE\.pi-web\plugins\i18n"

方式 B — npm 安装

npm install -g pi-web-i18n
# 然后创建符号链接，或直接复制到 PI WEB 插件目录：
mkdir -p ~/.pi-web/plugins
ln -s "$(npm root -g)/pi-web-i18n" ~/.pi-web/plugins/i18n

Windows（PowerShell）：

npm install -g pi-web-i18n
$src = Join-Path (npm root -g) "pi-web-i18n"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.pi-web\plugins" | Out-Null
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.pi-web\plugins\i18n" -Target $src

等 PI WEB 官方的插件发现机制完善后，也可以通过 Pi 包安装：npm:pi-web-i18n

方式 C — 克隆到别处再符号链接

git clone https://github.com/imHansiy/pi-web-i18n.git
mkdir -p ~/.pi-web/plugins
ln -s "$(pwd)/pi-web-i18n" ~/.pi-web/plugins/i18n

Windows（需开发者模式或管理员）：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.pi-web\plugins" | Out-Null
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.pi-web\plugins\i18n" -Target "D:\path\to\pi-web-i18n"

方式 D — 作为 Pi 包安装

Pi 包可以附带 PI WEB 浏览器插件。来源示例：

git:https://github.com/imHansiy/pi-web-i18n
# 或本地路径：
# file:C:/path/to/pi-web-i18n

在 PI WEB：设置 → Pi 包 安装上述来源，然后硬刷新浏览器（仅装包不会热替换浏览器插件）。

启用与验证

1. 硬刷新 PI WEB（Ctrl+F5 / Cmd+Shift+R）。

2. 打开：

   http://127.0.0.1:8504/pi-web-plugins/manifest.json

   应能看到 "id":"i18n"。

3. 默认界面语言为 zh-CN。切换：显示操作（Show Actions） → 搜索 Language → Language…。

4. 可选禁用（写入 PI WEB 配置，如 ~/.config/pi-web/config.json）：

{
  "plugins": {
    "i18n": { "enabled": false }
  }
}

改完后刷新浏览器标签页。

使用

| 操作 | 方法 | |------|------| | 切换语言 | 操作面板 → Language…，或 Ctrl+Shift+L / Cmd+Shift+L | | 重新套用翻译 | 语言弹层 → Re-apply | | 个人覆盖 | 编辑 locales/<id>.overlay.json（加载时合并，勿提交个人偏好） | | 扩充词条 | 编辑 locales/zh-CN.json → 硬刷新或 Re-apply |

词典结构：

{
  "meta": { "id": "zh-CN", "name": "简体中文", "nativeName": "简体中文" },
  "ui": {
    "Settings": "设置",
    "Select Theme": "选择主题"
  }
}

• 键 = 浏览器里出现的完整英文字符串（精确匹配）
• 值 = 译文
• 主题选择器等组合文案使用中间点 ·（U+00B7）与对勾 ✓，需与 PI WEB 源码一致

新增语言

1. 新建 locales/<id>.json（含 meta + ui）
2. 在 pi-web-plugin.js 的 KNOWN_LOCALES 中加入该 id
3. 硬刷新

目录结构

pi-web-i18n/
  package.json          # piWeb.plugins: [{ id: "i18n", module: "pi-web-plugin.js" }]
  pi-web-plugin.js      # 插件入口（Language… 操作）
  i18n-core.js          # 词典 / Shadow DOM 遍历 / MutationObserver
  locales/
    en.json
    zh-CN.json          # 主词典（约 1100+ 键）
    ja.json             # 日语起步
    *.overlay.json      # 可选个人覆盖
  scripts/
    scan-and-merge.mjs  # 可选：缺失键报告
  AGENTS.md             # 给 AI Agent 的安装与扩展说明
  README.md
  LICENSE

必填 PI WEB 元数据（勿破坏）：

{
  "piWeb": {
    "plugins": [
      { "id": "i18n", "module": "pi-web-plugin.js" }
    ]
  }
}

• 插件 id 须匹配 ^[a-z][a-z0-9.-]*$
• module 必须是包根目录下的相对路径
• 不支持旧式 piWeb.plugin / 仅字符串条目

限制

| 会翻译 | 不翻译 / 较难 | |--------|----------------| | 文本节点；title / aria-label / placeholder / alt | xterm 终端 | | 嵌套 open Shadow DOM（设置、选择器等） | CodeMirror 正文（占位符会译） | | 词典精确键 + 部分组合（·、✓、前缀） | 聊天气泡里的自由内容 | | 晚渲染的设置 / command-picker（短时 burst 重翻） | 无法保证 100% 动态模板 |

插件在首屏之后加载 → 可能短暂闪英文；插件有短时 FOUC 遮罩。

信任模型： 插件不在沙箱中运行，仅从你信任的来源安装。见 PI WEB trust model。

卸载

rm -rf ~/.pi-web/plugins/i18n
# Windows: Remove-Item -Recurse -Force "$env:USERPROFILE\.pi-web\plugins\i18n"

硬刷新浏览器。若通过 Pi 包安装，还需在 设置 → Pi 包 中移除。

开发

# 改 JS 或 locales 后硬刷新 http://127.0.0.1:8504
curl -s http://127.0.0.1:8504/pi-web-plugins/manifest.json | grep i18n

node scripts/scan-and-merge.mjs

面向 AI 的安装/扩展步骤见 AGENTS.md。

许可证

MIT

English

PI WEB has no official i18n API. This plugin translates the browser UI by matching English source strings → locale strings and rewriting text (and common attributes) inside open Shadow DOM trees.

Install (local plugin — recommended)

PI WEB loads local plugins from ~/.pi-web/plugins/<id>/ (or $PI_WEB_DATA_DIR/plugins if set). No rebuild or session-daemon restart.

Option A — clone into place

Linux / macOS / Git Bash

mkdir -p ~/.pi-web/plugins
git clone https://github.com/imHansiy/pi-web-i18n.git ~/.pi-web/plugins/i18n

Windows (PowerShell)

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.pi-web\plugins" | Out-Null
git clone https://github.com/imHansiy/pi-web-i18n.git "$env:USERPROFILE\.pi-web\plugins\i18n"

Option B — npm install

npm install -g pi-web-i18n
# then symlink or copy into PI WEB plugin directory:
mkdir -p ~/.pi-web/plugins
ln -s "$(npm root -g)/pi-web-i18n" ~/.pi-web/plugins/i18n

Windows (PowerShell):

npm install -g pi-web-i18n
$src = Join-Path (npm root -g) "pi-web-i18n"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.pi-web\plugins" | Out-Null
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.pi-web\plugins\i18n" -Target $src

PI WEB's plugin discovery may also load this from a Pi package source npm:pi-web-i18n when federation supports it.

Option C — clone elsewhere, symlink

git clone https://github.com/imHansiy/pi-web-i18n.git
mkdir -p ~/.pi-web/plugins
ln -s "$(pwd)/pi-web-i18n" ~/.pi-web/plugins/i18n

Windows (Developer Mode or admin):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.pi-web\plugins" | Out-Null
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.pi-web\plugins\i18n" -Target "D:\path\to\pi-web-i18n"

Option D — Pi package (if you prefer pi install)

A Pi package may ship PI WEB browser plugins. Source examples:

git:https://github.com/imHansiy/pi-web-i18n
# or a local path:
# file:C:/path/to/pi-web-i18n

In PI WEB: Settings → Pi packages → install that source.
Then hard-reload the browser so the PI WEB plugin is discovered (package install alone does not hot-swap browser plugins).

Enable & verify

1. Hard-reload PI WEB (Ctrl+F5 / Cmd+Shift+R).

2. Open:

   http://127.0.0.1:8504/pi-web-plugins/manifest.json

   You should see a plugin with "id":"i18n" (source local or package scope).

3. Default UI language is zh-CN. To switch: Show Actions → search Language → Language….

4. Optional disable in PI WEB config (~/.config/pi-web/config.json or your install’s config):

{
  "plugins": {
    "i18n": { "enabled": false }
  }
}

Reload the browser tab after changing enablement.

Usage

| Action | How | |--------|-----| | Switch language | Actions → Language…, or Ctrl+Shift+L / Cmd+Shift+L | | Re-apply translations | Language picker → Re-apply | | Personal overrides | Edit locales/<id>.overlay.json (merged on load; not committed personal prefs) | | Extend dictionary | Edit locales/zh-CN.json → hard reload or Re-apply |

Dictionary shape:

{
  "meta": { "id": "zh-CN", "name": "简体中文", "nativeName": "简体中文" },
  "ui": {
    "Settings": "设置",
    "Select Theme": "选择主题"
  }
}

• Key = exact English UI string as shown in the browser
• Value = translation
• Composite theme labels use middle-dot · (U+00B7) and checkmark ✓ as in PI WEB source

Add a locale

1. Add locales/<id>.json (meta + ui).
2. Append <id> to KNOWN_LOCALES in pi-web-plugin.js.
3. Hard-reload.

Layout

pi-web-i18n/
  package.json          # piWeb.plugins: [{ id: "i18n", module: "pi-web-plugin.js" }]
  pi-web-plugin.js      # plugin entry (Language… action)
  i18n-core.js          # catalogs, Shadow DOM walk, MutationObserver
  locales/
    en.json
    zh-CN.json          # main dictionary (~1100+ keys)
    ja.json             # starter
    *.overlay.json      # optional personal merges
  scripts/
    scan-and-merge.mjs  # optional missing-key report
  AGENTS.md             # instructions for AI agents
  README.md
  LICENSE

Required PI WEB metadata (do not break this):

{
  "piWeb": {
    "plugins": [
      { "id": "i18n", "module": "pi-web-plugin.js" }
    ]
  }
}

• Plugin id must match ^[a-z][a-z0-9.-]*$
• module must be a relative path inside the package root
• No legacy piWeb.plugin / string-only entries

Limitations

| Translated | Not / hard | |------------|------------| | Text nodes, title / aria-label / placeholder / alt | xterm terminal | | Nested open Shadow DOM (settings, pickers) | CodeMirror document body (placeholder is translated) | | Exact dictionary keys + some composites (·, ✓, prefixes) | Free-form agent chat content | | Late-rendered settings / command-picker (burst re-apply) | 100% of every dynamic template |

Plugins load after first paint → brief English flash is possible; the plugin uses a short FOUC guard.

Trust: plugins are not sandboxed. Install only from sources you trust. See PI WEB trust model.

Uninstall

rm -rf ~/.pi-web/plugins/i18n
# Windows: Remove-Item -Recurse -Force "$env:USERPROFILE\.pi-web\plugins\i18n"

Hard-reload the browser. If installed as a Pi package, remove it from Settings → Pi packages as well.

Development

# after editing JS or locales
# hard-reload http://127.0.0.1:8504
curl -s http://127.0.0.1:8504/pi-web-plugins/manifest.json | grep i18n

node scripts/scan-and-merge.mjs

For agent-oriented install/extend steps, see AGENTS.md.

License

MIT