---
name: deepl-glossary-translation
description: >
  pdf-spec-mcp と DeepL MCP Server を連携させ、PDF仕様書（ISO 32000-2）を用語統一された日本語に翻訳するSkill。
  グロッサリー（用語集）の作成・登録・適用までの一連のワークフローをガイドする。
  Skill + MCP + MCP 連携パターンの実装例。
  以下のリクエストで使用すること：
  PDF仕様の翻訳、グロッサリー作成、用語集の管理、専門用語の統一翻訳、
  DeepLでの技術文書翻訳、pdf-spec-mcpとDeepLの連携、MCP間連携の例。
---

# PDF仕様書グロッサリー翻訳 Skill

pdf-spec-mcp（用語抽出）と DeepL MCP Server（翻訳）の2つのMCPサーバーを
橋渡しし、一貫性のある日本語翻訳を実現する。

## アーキテクチャ

```
pdf-spec-mcp ──[get_definitions]──→ 71用語を抽出
        │
   ドメイン知識による分類（人間 or AI）
        │
        ├─ 15用語：略語（ASCII, JPEG等）→ そのまま保持
        └─ 56用語：対訳を指定 → TSV形式のグロッサリー
                                      │
DeepL API ←──[POST /v3/glossaries]────┘  ※ DeepL MCPに書込みツールがないためAPI直接呼出し
        │
        └─ glossary_id を取得
                │
DeepL MCP ──[translate-text + glossaryId]──→ 用語統一された日本語翻訳
```

## 前提条件

以下を確認してから作業を開始する：

1. **MCP サーバーが利用可能か**
   - `pdf-spec-mcp` のツール（`get_definitions`, `get_section` 等）にアクセスできるか
   - `DeepL MCP Server` のツール（`translate-text`）にアクセスできるか

2. **DeepL API キーが設定済みか**
   - 環境変数 `DEEPL_API_KEY` が設定されていること
   - 未設定の場合、ユーザーに https://www.deepl.com/your-account/keys を案内する

3. **既存グロッサリーの有無**
   - DeepL MCP の `list-glossaries` ツールで既存グロッサリーを確認する
   - 「PDF Spec ISO32000-2 EN-JA」が既にあればステップ3まではスキップ可能

## ワークフロー

### ステップ1：用語を抽出する

pdf-spec-mcp の `get_definitions` ツールを呼び出し、ISO 32000-2 のセクション3から全用語を取得する。

```
ツール: get_definitions（pdf-spec-mcp）
パラメータ:
  rfc: 不要（PDF仕様書を対象とするため）
```

返却される71用語をリスト化する。

### ステップ2：用語を分類し、対訳を決定する

抽出した用語を以下の2カテゴリに分類する：

**A. そのまま保持する略語・固有名詞（約15語）**
ASCII, ASN.1, CMap, DCT, JPEG, JPEG2000, PostScript, Type 0/1/3, Unicode, UTF-8, UTF-16BE, UTF-32, XML

これらはグロッサリーに**含めない**（DeepLが原文のまま保持するため）。

**B. 日本語の対訳を指定する用語（約56語）**
TSV形式（タブ区切り）で対訳表を作成する。

参考用の完成済みグロッサリーが `references/pdf-spec-glossary-en-ja.tsv` にある。
新規作成する場合は、このファイルをテンプレートとして参照する。

**対訳決定の指針：**
- PDF仕様書の文脈で最も一般的に使われる訳語を選ぶ
- カタカナ語として定着しているものはカタカナにする（例：glyph → グリフ）
- 技術的に正確な日本語がある場合はそちらを優先する（例：cross-reference table → 相互参照テーブル）
- 大文字/小文字の区別が意味を持つ場合は注意する（例：null は小文字のまま）

### ステップ3：グロッサリーを DeepL API に登録する

DeepL MCP Server にはグロッサリーの作成ツールがないため、API を直接呼び出す。

**方法A：バンドルスクリプトを使う**

```bash
export DEEPL_API_KEY="your-key-here"
bash scripts/create-glossary.sh
```

スクリプトが Free/Pro を自動判別し、グロッサリーを登録して `glossary_id` を返す。

**方法B：curl で手動登録する**

```bash
# エンドポイント判定（キーが :fx で終わる → Free）
if [[ "$DEEPL_API_KEY" == *":fx" ]]; then
  ENDPOINT="https://api-free.deepl.com"
else
  ENDPOINT="https://api.deepl.com"
fi

# TSVの内容をJSON用にエスケープ
ENTRIES=$(cat references/pdf-spec-glossary-en-ja.tsv | sed 's/\t/\\t/g' | paste -sd'\\n' -)

curl -s "${ENDPOINT}/v3/glossaries" \
  -H "Authorization: DeepL-Auth-Key ${DEEPL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"PDF Spec ISO32000-2 EN-JA\",
    \"source_lang\": \"en\",
    \"target_lang\": \"ja\",
    \"entries_format\": \"tsv\",
    \"entries\": \"${ENTRIES}\"
  }"
```

**返却された `glossary_id` を必ず控える。** 以降の翻訳で毎回使用する。

### ステップ4：グロッサリー付きで翻訳する

DeepL MCP の `translate-text` ツールを使い、グロッサリーを適用して翻訳する。

```
ツール: translate-text（DeepL MCP）
パラメータ:
  text: <翻訳対象の英文>
  sourceLangCode: "en"        ← グロッサリー使用時は必須
  targetLangCode: "ja"
  glossaryId: "<ステップ3で取得したID>"
```

**重要：** `glossaryId` を指定する場合、`sourceLangCode` の指定が**必須**になる。
省略すると言語自動検出モードになり、グロッサリーが適用されない。

### ステップ5（応用）：セクション取得と翻訳を一気通貫で行う

ユーザーから「セクション X を日本語で読みたい」と言われた場合：

1. `get_section`（pdf-spec-mcp）でセクション内容を取得
2. `translate-text`（DeepL MCP）でグロッサリー付き翻訳

```
例：「7.3.7節を日本語で読みたい」

→ get_section(rfc: 32000, section: "7.3.7")
→ translate-text(text: <取得した内容>, sourceLangCode: "en", targetLangCode: "ja", glossaryId: "<ID>")
```

## グロッサリーの更新

用語の追加・修正が必要な場合：

1. TSVファイルを編集する
2. DeepL API の PUT エンドポイントで辞書を更新する

```bash
curl -X PUT "${ENDPOINT}/v3/glossaries/${GLOSSARY_ID}/dictionaries/en/ja" \
  -H "Authorization: DeepL-Auth-Key ${DEEPL_API_KEY}" \
  -H "Content-Type: text/tab-separated-values" \
  --data-binary @references/pdf-spec-glossary-en-ja.tsv
```

## 翻訳品質の検証（オプション）

xcomet MCP が利用可能な場合、翻訳品質をスコアリングできる：

```
ツール: xcomet_evaluate
パラメータ:
  source: <原文>
  translation: <翻訳結果>
  source_lang: "en"
  target_lang: "ja"
```

スコアが 0.8 未満の場合、グロッサリーの用語追加や翻訳の手動調整を検討する。

## 制限事項

- グロッサリーは ISO 32000-2 セクション3の定義用語が対象。各章固有の用語は別途追加が必要
- 翻訳方向は EN→JA の一方向のみ
- DeepL MCP Server にグロッサリー書込みツールが追加された場合、ステップ3は MCP 経由に置き換え可能