Translation Quality

Translation Quality — Multi-Agent Professional Translation

This skill orchestrates a complete professional translation pipeline using Agent Teams. It combines:

• Translation with structure preservation (absorbs translation-layout)
• Terminology verification via web search (new capability)
• Independent quality review (new capability)
• Revision based on review feedback (new capability)
• Professional document typesetting (absorbs formal-doc-layout)

Architecture Overview

              User: "翻译这个文档"
                      │
            Team Lead (this session)
            TeamCreate ─ estimate terms
                      │
    ┌─────────────────┼──────────────────┐
    │           ≤50 terms │ >50 terms    │
 translator    term-      │ term-fast    reviewer
 (Sonnet)      researcher │ term-deep    (Opus)
    │          (Sonnet)   │ (both Sonnet) (waiting)
 Phase 1A:     Phase 1B: │ Phase 1B:       │
 First-pass    web search │ parallel        │
 translation   verify     │ search          │
    │              │      │   │  │          │
    │              │    Phase 1.5:          │
    │              │    Lead merges →       │
    │    ← terminology-glossary.json →     │
    ├──────────────┼───────────────────────┤
    │           Phase 2: reviewer          │
    │    ← review feedback →               │
 Phase 3: revision                         │
    │     Phase 4: Typesetting → .docx/.pdf

Prerequisites

Agent Teams must be enabled:

• Add "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" to ~/.claude/settings.json under "env", OR
• Export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in shell profile

---

Phase 0: Team Lead Preparation

0.1 Read and Analyze Source Document

Read the source document completely. Determine:

• Source language and target language
• Document type (conference agenda, contract, report, academic paper, etc.)
• Estimated length (pages/sections)
• Whether specialized terminology is present

Source format handling (critical for structure preservation):

• If source is .doc or .docx, convert with textutil -convert html (NOT txt).

Plain text conversion STRIPS all table structure — the translator cannot preserve tables it cannot see.

• Save HTML to /tmp/translation-workspace/source.html
• Also copy the original file for reference

Chunking (if >10 pages):

1. Estimate pages: count paragraphs in HTML body, ~35 paragraphs ≈ 1 page
2. If ≤10 pages: skip chunking, proceed as single-chunk mode
3. If >10 pages: identify chapter boundaries in HTML — look for:

• `, ` tags, OR
• Bold paragraphs with larger font-size (Word's heading style), OR
• Paragraphs matching "一、" "二、" "三、" etc. (Chinese section numbering)

1. Group sections into chunks of ≤10 pages each. Never split inside a `` block
2. Save chunks to /tmp/translation-workspace/chunks/chunk-{N}.html
3. Record boundaries in /tmp/translation-workspace/chunk-manifest.md

Structural manifest — the lead MUST produce before spawning agents: Scan the source (use .html version) and record:

• Number of tables, each table's column count and row count
• Content that lives INSIDE table cells (especially multi-item cells like

"10 presentations listed inside a single schedule row") Save to /tmp/translation-workspace/structure-manifest.md

0.2 Create Workspace

# Create a workspace directory for this translation
mkdir -p /tmp/translation-workspace

All agents will read from and write to this workspace.

0.3 Define Contracts

Before spawning any teammate, define these contracts:

Contract 1 — Terminology Glossary (term-researcher → translator, reviewer): See references/glossary-schema.md for full JSON schema and example. Confidence: high (2+ sources), medium (1 source), low (best judgment). Categories: organization, person, place, venue, title, technical, product, event

Contract 2 — Review Feedback (reviewer → translator): See references/review-feedback-schema.md for format and example. Issue types by priority: FABRICATION > OMISSION > TERMINOLOGY > ACCURACY > STRUCTURE > REGISTER

Contract 3 — Workspace Paths:

/tmp/translation-workspace/
├── source.* / source.html          # Source document + HTML conversion
├── structure-manifest.md           # Lead's structural inventory
├── chunks/                         # Only if >10 pages
│   └── chunk-{N}.html
├── chunk-manifest.md               # Chunk boundaries (if chunked)
├── first-pass.md                   # Merged translation (single or concatenated chunks)
├── first-pass-chunk-{N}.md         # Per-chunk output (if chunked)
├── structure-report[-chunk-{N}].md # Structure audit (per chunk if chunked)
├── glossary-fast.json              # Split mode only: names, places
├── glossary-deep.json              # Split mode only: orgs, technical
├── terminology-glossary.json       # Final merged glossary (always)
├── review-feedback.md              # Reviewer feedback (on merged first-pass.md)
└── final-translation.md            # Final revised translation

0.4 Create Team and Tasks

TeamCreate("translation-team")

Estimate term count: scan source for org suffixes (协会/委员会/公司/集团/局/院/所),
quoted proper nouns, person names with titles, and English acronyms.
Heuristic: ~8-10 proper nouns per page. A 7-page doc ≈ 60-70 terms → split mode.

If single chunk (≤10 pages):
  Task 1: "First-pass translation" → translator (Sonnet)
  If ≤50 terms (estimated):
    Task 2: "Verify terminology" → term-researcher (Sonnet)
  If >50 terms (estimated):
    Task 2a: "Verify terminology (fast: names, places)" → term-researcher-fast (Sonnet)
    Task 2b: "Verify terminology (deep: orgs, technical)" → term-researcher-deep (Sonnet)
    Both 2a+2b run in PARALLEL. Lead merges outputs before reviewer starts (Phase 1.5).
  Task 3: "Review translation"     → reviewer (Opus), depends on Task 1 + Task 2 (or 2a+2b)
  Task 4: "Revise translation"     → translator, depends on Task 3

If N chunks (>10 pages):
  Task 1..N:  "Translate chunk {i}" → translator-{i} (one Sonnet agent per chunk)
  Term tasks: same ≤50/>50 split as above (Task N+1, or N+1a and N+1b)
  Task N+2:   "Review translation"  → reviewer (depends on all prior tasks)
  Task N+3:   "Revise translation"  → translator-1 (depends on Task N+2)

All translators run in PARALLEL. term-researcher(s) also run in parallel with them.
Reviewer waits for ALL to complete.

Model assignments:
  translator / translator-{N}:  Sonnet (model: sonnet) — speed for volume
  term-researcher:               Sonnet (model: sonnet) — web search + extraction
  term-researcher-fast (split):  Sonnet (model: sonnet) — names, places
  term-researcher-deep (split):  Sonnet (model: sonnet) — orgs, technical terms
  reviewer:                      Opus   (model: opus)   — maximum accuracy for review

---

Phase 1: Parallel Execution

Spawn Prompt — translator (Sonnet)

You are the translator for this team. Your model should be Sonnet for speed.

OWNERSHIP:
- You own: /tmp/translation-workspace/first-pass.md, /tmp/translation-workspace/final-translation.md
- Do NOT modify any other workspace files

TASK — PHASE 1 (First-pass translation):
1. Read the structure manifest at /tmp/translation-workspace/structure-manifest.md
2. Read the source document at [SOURCE_PATH] (use .html version if available)
3. Translate from [SOURCE_LANG] to [TARGET_LANG]
4. Save to /tmp/translation-workspace/first-pass.md

STRUCTURE PRESERVATION RULES (critical):
These rules ensure the translation mirrors the original document's structure exactly.

Tables:
- Same number of columns, same column order, same column purposes
- Same number of rows with 1:1 row correspondence
- If original merges cells, merge the same cells
- NEVER convert tables to lists or lists to tables
- NEVER add/remove/reorder columns
- Content inside a table row in the original MUST stay inside a table row

COMMON VIOLATIONS (from real failures — do NOT repeat):
- Transportation table was converted to H2 headings + paragraphs because
  the .txt source lost table markup. ALWAYS use the .html source.
- 10 keynote presentations inside a single table cell (09:00-12:00 row)
  were pulled out as free text below the table. If items are inside a cell,
  they STAY inside that cell, even if the cell content is long.
- Dining info as free text (field: value) was converted to a table.
  Free text stays free text — do not create tables that don't exist in source.

Headings:
- Match heading hierarchy level for level (H1→H1, H2→H2)
- Do not add or remove headings

Lists:
- Preserve numbering scheme and nesting depth
- Ordered stays ordered, unordered stays unordered

Paragraphs:
- Maintain exact content sequence — paragraph order must not change
- Do not merge or split paragraphs
- Preserve alignment (centered stays centered)

MANDATORY STRUCTURE REPORT:
Before saving first-pass.md, write /tmp/translation-workspace/structure-report.md:

For EACH table in the structure manifest:
  Table [N]: source=[R] rows x [C] cols → translation=[R] rows x [C] cols

For content boundaries:
  List every multi-item cell from the manifest, confirm items stayed inside:
    Table [N] row [R]: "[content summary]" → inside cell / BOUNDARY VIOLATION

Totals: [N] tables matched, [N] boundary violations
If boundary violations > 0, FIX before saving first-pass.md.

ANTI-FABRICATION RULES:
- NEVER invent content not in the source
- If unclear, mark as [unclear in original]
- Mark uncertain terminology with [?原文?] for the term-researcher to verify
- Person names: transliterate from pinyin, never replace with different names
- Venue names that are proper nouns within a building: transliterate (e.g., 美泉宫 as a conference room → "Meiquangong Hall"), do not translate as the famous landmark
- Numbers, dates, booth numbers: copy exactly from source

COMMUNICATION:
- After saving first-pass.md, mark Task 1 as completed
- Wait for Task 4 to be assigned — you will receive review feedback
  and terminology glossary via SendMessage
- For Phase 3 (revision): apply ALL critical and major fixes from
  review-feedback.md, apply glossary corrections, then save to
  /tmp/translation-workspace/final-translation.md and mark Task 4 complete

REVISION STRUCTURE PROTECTION (critical):
  During revision, you MUST only change text — NEVER restructure the document.
  - Do NOT pull content out of table cells into free text
  - Do NOT convert table cells with  line breaks into numbered lists outside the table
  - Do NOT convert free text sections into tables
  - Do NOT change the number of rows or columns in any table
  - Keep all multi-item cells intact: replace terms IN PLACE using find-and-replace
  - If in doubt, use exact string replacement rather than rewriting sections
  Violation of these rules was observed in real testing and caused 13 structure failures.

Spawn Prompt — translator-{N} (Sonnet) [chunked mode]

Same rules as the standard translator prompt above, with these overrides:

• SOURCE: Read /tmp/translation-workspace/chunks/chunk-{N}.html
• OUTPUT: Save to /tmp/translation-workspace/first-pass-chunk-{N}.md
• STRUCTURE REPORT: Save to /tmp/translation-workspace/structure-report-chunk-{N}.md
• Read the GLOBAL structure-manifest.md (covers all tables in all chunks)
• Read the GLOBAL terminology-glossary.json (when available)
• Your chunk covers: [SECTIONSFROMCHUNK_MANIFEST]
• Mark Task {N} complete when done

Spawn Prompt — term-researcher (Sonnet)

You are the terminology researcher for this team.

OWNERSHIP:
- You own: /tmp/translation-workspace/terminology-glossary.json
- Do NOT modify any other workspace files

TASK:
1. Read the source document at [SOURCE_PATH]
2. Extract ALL:
   - Organization names (协会, 委员会, 公司, 集团, etc.)
   - Person names with titles
   - Place names and venue names
   - Event names and conference names
   - Technical/specialized terms
   - Product names and brand names
   - Any proper noun

3. For EACH term, verify via web search (try in order):
   "[原文]" official English name → site:official-website → org's own English page →
   bilingual government/industry databases → person's published English name
   If translating EN→ZH, reverse search direction.

4. Score confidence: high (2+ sources agree), medium (1 source), low (best judgment)
5. Record source URLs as evidence for every term
6. Save JSON to /tmp/translation-workspace/terminology-glossary.json
   following the schema in `references/glossary-schema.md`
7. SendMessage glossary summary to "translator" and "reviewer"
8. Mark your task as completed

IMPORTANT: Search in batches of 5 terms. For low-confidence terms, clearly note this.

WEB SEARCH FALLBACK: If a search fails or times out, retry once. After 2 consecutive
failures for a term, mark it as confidence: "low" with notes: "web search unavailable"
and MOVE ON. Do NOT block the entire glossary for a few unreachable terms. If ALL
searches fail (service down), produce a glossary using best judgment for all terms,
mark all as low confidence, and note "web search unavailable" in metadata.

Record timing: note your start time and end time in metadata (ISO 8601) so Lead can
measure researcher duration for future threshold calibration.

Spawn Prompt — term-researcher-fast (Sonnet) [split mode, >50 terms]

Same rules as the standard term-researcher prompt, with these overrides:

• SCOPE: Person names, place names, venue names, product names ONLY
• Skip: organizations, technical terms, event names (handled by deep researcher)
• Search strategy: prioritize Google Scholar, ResearchGate, university websites
• For person names: check published English name, default to standard Pinyin
• OUTPUT: Save to /tmp/translation-workspace/glossary-fast.json
• Mark your task complete when done. Do NOT write to terminology-glossary.json.

Spawn Prompt — term-researcher-deep (Sonnet) [split mode, >50 terms]

Same rules as the standard term-researcher prompt, with these overrides:

• SCOPE: Organization names, technical/specialized terms, event names ONLY
• Skip: person names, place names, venues, products (handled by fast researcher)
• Search strategy: prioritize official websites, government databases, industry associations
• OUTPUT: Save to /tmp/translation-workspace/glossary-deep.json
• Mark your task complete when done. Do NOT write to terminology-glossary.json.

Spawn Prompt — reviewer (Opus)

You are the quality reviewer for this team. Use Opus model for maximum accuracy.

OWNERSHIP:
- You own: /tmp/translation-workspace/review-feedback.md
- Do NOT modify any other workspace files

TASK:
Wait for Tasks 1 and 2 (or 2a+2b) to both complete, then:

1. Read the source document at [SOURCE_PATH]
2. Read the first-pass translation at /tmp/translation-workspace/first-pass.md
3. Read the terminology glossary at /tmp/translation-workspace/terminology-glossary.json
   PRE-CHECK: Verify glossary has total_terms > 0 and the count is plausible
   for the document size (~8-10 terms/page). If glossary is empty or missing,
   alert Lead via SendMessage before proceeding — do NOT review without it.

4. Perform a systematic review with these priorities (highest first):

   a. FABRICATION CHECK (critical):
      - Go paragraph by paragraph through the translation
      - For EACH paragraph, verify it corresponds to source content
      - Flag ANY content in the translation that does not exist in the source
      - Flag any numbers, names, or facts that differ from the source

   b. STRUCTURE CHECK (critical):
      Read /tmp/translation-workspace/structure-manifest.md (lead's counts)
      and /tmp/translation-workspace/structure-report.md (translator's counts).
      Independently verify:
      - For EACH table: count rows and columns in source vs translation
      - For EACH multi-item cell: verify items are still inside the cell
      - No free text → table or table → free text conversions
      Output a STRUCTURE COMPARISON TABLE in the review:
      | E

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [senshinji](https://github.com/senshinji)
- **Source:** [senshinji/claude-translation-skill](https://github.com/senshinji/claude-translation-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.