translate-pseudocn git:20260913.a915692A

Immutable. This exact content is served forever at /api/v1/blob/2182241e60482bec.

---
name: translate-pseudocn
description: 为文档撰写技能提供伪中国语（pcn）语言支持。以日语汉字词汇为基础、剥离平假名与片假名、保留日语语序的伪本地化。可被 write-project-docs 自动发现调用。
language_code: pcn
display_name: 偽中国語
base_language: ja
---

# 伪中国语翻译

为 NixKits 文档体系提供 pcn（伪中国语）语言。

## 自动发现契约

write-project-docs / write-maintenance-log 通过扫描 `skills/translate-*/SKILL.md` frontmatter 自动发现：

| 字段 | 值 | 用途 |
|------|-----|------|
| `language_code` | `pcn` | 目录名、文件扩展名 |
| `display_name` | `偽中国語` | 语言切换器标签 |
| `base_language` | `ja` | 源语言 |

## 设计原则

伪中国语是**日语文本剥离假名后的视觉结果**，不是中文翻译。

- **基于智能体自然语言理解进行转换**，不使用自动化脚本/正则替换。理解句子结构后再做转换。
- 语序转换为中文语序（SOV → SVO）
- 日文汉字名词保持原样
- 片假名外来语优先查词典映射为日本汉字，未命中则剥离
- **禁止使用简体中文或繁体中文汉字**（如「软件」「安装」「模块」）

## 替换规则

### 1. 剥离假名

去除**所有平假名**（あ-ん）。片假名（ア-ン）按以下优先级处理：

1. 查 [`dictionary.md`](dictionary.md) 映射为日本汉字
2. 未命中 → 剥离（仅保留上下文中的日文汉字）

### 2. 保留日文汉字

日文汉字名词**原样保留**，包括：

| 示例 | 保留形式 | 说明 |
|------|---------|------|
| 開発 | 開発 | 日文汉字，非「开发」 |
| 環境 | 環境 | 日文汉字 |
| 管理 | 管理 | 日文汉字 |
| 提供 | 提供 | 日文汉字 |
| 設定 | 設定 | 日文汉字 |
| 情報 | 情報 | 日文汉字 |

### 3. 保留日语语序

日语 SOV 语序转换为中文 SVO 语序（主-动-宾）。

### 4. 助词转换（最小化）

助词适当保留以增加文本丰富性，仅剥离无实义的语法标记：

| 日文 | 変換 | 条件 |
|------|------|------|
| の | 之 | 所有/所属 |
| と | 與 | 并列连接 |
| に | 於 | 方向/目标 |
| で | 以 | 手段/场所 |
| から | 自 | 起点 |
| まで | 至 | 终点 |
| は | (剥离) | 主题标记，无实义 |
| が | (剥离) | 主语标记，无实义 |
| を | (剥离) | 宾语标记，无实义 |


### 5. 标点

日文标点保持原样（`、` `。` 不转换）。

### 6. 代码块保护

- Nix 代码块：仅翻译 `#` 注释行
- Bash 代码块：全部不动
- 先按 ` ``` ` 边界提取代码块，仅对非代码区域应用规则

## 验证

翻译完成后，使用以下脚本检查输出文件是否残留假名：

```python
import re

def check_kana(path):
    with open(path) as f:
        text = f.read()
    blocks = re.split(r'```', text)
    outside = ''.join(blocks[i] for i in range(0, len(blocks), 2))
    kata = re.findall(r'[\u30A0-\u30FF]{2,}', outside)
    hira = re.findall(r'[\u3040-\u309F]{2,}', outside)
    if kata: print(f'残片假名: {kata}')
    if hira: print(f'残平假名: {hira}')
```

## 词典

片假名→日本汉字映射见 [`dictionary.md`](dictionary.md)。仅包含有对应日本汉字词的片假名外来语。

## 注意事项

- 伪中国语是视觉伪本地化，外观是「汉字+符号」的日文文本
- 禁止使用简体中文汉字（如「软件」「安装」「模块」「设置」）
- 语言切换器生成：从日文源提取路径逐个精确构造
- `日本語`→`[日本語]`（加链接），自身标签 `偽中国語`（纯文本）
- 验证发现的残留片假名应立即翻译并加入 [`dictionary.md`](dictionary.md)，然后重新生成所有 pcn 文档

## 常见陷阱与修复（实战经验）

### 1. 片假名词典映射必须优先于剥离

所有片假名在剥离前**必须先查词典**。常见遗漏项及对应日文汉字：

| 片假名 | 日文汉字 | 常见出现问题 |
|--------|---------|-------------|
| タイプ | 種別 | 基本信息表格的类型行变为空列 |
| アイコン | 図標 | 图标行显示空值 |
| タイル | 磁貼 | 标题行丢失 |
| サービス | 服務 | 服务模块描述缺失主体 |
| リング | 環 | UI 环形用量指示缺失主体 |
| キー | 鍵 | 键名相关描述出现空格 |
| セッション | 会期 | 会话相关段落丢失主体 |
| プレフィル | 前置充填 | LLM 推论文档中推理阶段名残留英文 |
| ボトルネック | 隘路 | 性能分析段落残留英文 |
| トークン | 語彙 | LLM 文档中计量单位混用（既有文档用「語彙」，须一致） |

**验证方法**：翻译完成后，对所有 pcn 文件运行残留假名检查脚本（见上方「验证」节）。
同时额外检查表格中是否存在空列（`grep '^|  |' docs/pcn/*.md`）。

### 2. 语言切换器必须双向更新

新增 pcn 文件后，**所有现有语言版本**的同一文档都需要追加 `[偽中国語]` 链接。
仅更新 pcn 文件自身的切换器是不够的——zh/en/ja 的切换器行同样需要新增条目。

### 3. 禁止使用简体中文汉字

日文汉字「開発」「環境」「設定」「情報」必须原样保留，绝不能替换为简体中文的「开发」「环境」「设置」「信息」。

### 4. 标点保持日文

日文标点 `、` `。` 不转换为中文 `，` `。`。

### 5. 子代理生成文件的切换器必须包含全部语言

子代理生成新语言文件时，容易只输出 **3 条目切换器**（如 `[中文] | [English] | [偽中国語]`），缺少其他已安装的扩展语言链接（如 `[日本語]`）。父代理在接收子代理输出后，**必须验证并补全**切换器至所有已发现语言。

验证命令：
```bash
# 检查切换器是否包含全部 5 语言
for f in docs/pcn/*.md; do
  line=$(grep '^\[中文\]' "$f")
    echo "$line" | grep -q "$expected" || echo "MISSING $expected in $f"
  done
done
```
### 6. 本地化文档内链必须指向同语言版本

模块文档表格中的链接指向源语言文档。转换为 pcn 后必须改为指向 pcn 版。例如 `](ja/nginx.md)` → `](./nginx.md)`。同时注意顶层文档的跨深度链接调整（`../LICENSE` → `../../LICENSE`）。

### 7. 繁体/简体判定：先分类，再替换

清理既有 pcn 文档的简繁混用时，**不可对候选字表做无差别 `sed` 替换**——大量「简体形」字符同时也是**合法日文汉字**，改了就是破坏。

实测：对 55 字候选表做全量扫描，真正的简体专属字**仅 5 个**（`档` `径` `译` `说明` `实例`），其余多为一字多用的日文汉字。

| 类别 | 例 | 处理 |
|------|-----|------|
| **日文汉字（合法，勿改）** | `更新` `停止` `管理` `保存` `設定` `情報` `機能` `記録` `実測` | 保留 |
| **简体专属（须改）** | `与`→`與`、`档`→`檔`、`径`→`経`、`译`→`訳`、`说明`→`説明`、`实例`→`実例` | 替换 |
| **中文词，日语有对应字** | `端口`（ポート）、`制御台`（コンソール） | **保留并计入词典**，见下 |

**判定方法**：不要凭字形猜测，用「该字是否出现在日文汉字集内」过滤后再替换。简体专属字集与日文汉字集高度重叠，凭感觉必误。

### 8. 中文词 ≠ 违规：日语有对应字者应入词典

`端口`、`制御台` 这类词**看似**中文，但日语中存在对应汉字，故不应剥离或改写，而应**作为假名外来语的汉字化映射计入词典**：

| 假名 | 映射 | 理由 |
|------|------|------|
| ポート | 端口 | 日文「港」义 |
| コンソール | 制御台 | 管理/监控控制台 |

**反例（我犯过的错）**：曾把无词典映射的 `ポート` 按「未命中→剥离」处理，自创了 `港`。这既违反规则（剥离≠另造），又与既有文档不一致。**未命中时的正确动作是「查证并补入词典」，而非「自创映射」或「裸剥离」。**

### 9. 提交信息（commit subject）保持 verbatim

维护日志的 `| 提交 | 説明 |` 表中，**提交信息列必须原样保留**，即使是中文简体、即使 pcn 其它部分已伪中国语化。

依据：`docs/MAINTENANCE.ja.md` 的同一列同样保留中文原样——git 提交信息是**不可变的外部引用**，与 AGENTS.md 节标题同理。

判定方法（区分「摘要」与「提交」列）：

```bash
# 提交行以 | `7位SHA` | 开头；摘要行以 **摘要** 开头
grep -nE '^\| `[0-9a-f]{7}` \|' docs/MAINTENANCE.pcn.md   # 这些行豁免
grep -n '^\*\*摘要\*\*' docs/MAINTENANCE.pcn.md            # 这些行须合规
```

> ⚠️ 实战：一次全仓清理中，扫描器报出 4 处简体字，逐一核对后确认**全部位于提交信息列**——属正确保留，非违规。若不加区分地替换，会篡改 git 历史引用。

### 10. 清理前先留基线，改后校验「内容无损」

批量替换易误伤。**动手前**对全部 pcn 文件留存快照，**改后**比对行数：

```bash
# 改前
mkdir -p /tmp/pcn-baseline
for f in $(find docs/pcn -name '*.md'); do
  cp "$f" "/tmp/pcn-baseline/$(echo $f | tr '/' '_')"
done

# 改后：行数应逐一相同
for f in $(find docs/pcn -name '*.md' | sort); do
  b="/tmp/pcn-baseline/$(echo $f | tr '/' '_')"
  a=$(wc -l < "$b"); c=$(wc -l < "$f")
  [ "$a" != "$c" ] && echo "DIFF $f: $a -> $c"
done
```

同长度替换（简→繁、词→词）应使行数**完全不变**；出现差异即说明误伤换行或内容。