claude-fidelity-translator

claude-fidelity-translator

A Claude skill for translating documents where mistranslation has consequences.

Aerospace flight manuals, pharmaceutical SOPs, medical-device IFUs, automotive safety cases, nuclear operating procedures, legal contracts. Documents where a WARNING rendered as a CAUTION is a defect, where "shall" softened to "should" changes legal force, and where the same source term rendered three different ways across three chapters means a reviewer has to read every page twice.

fidelity-translator is built for that work. It is not optimised for speed or fluency — it is optimised for terminology consistency, verifiability of safety-critical content, and structural fidelity to the source document family.

Install

Option 1 — As a Claude plugin (recommended)

In any Claude Code or Cowork session:

/plugin marketplace add Tasdax123/claude-fidelity-translator
/plugin install fidelity-translator@fidelity-tools

Replace <owner> with the GitHub owner of your fork or the canonical repo.

Option 2 — Standalone skill copy

Clone the repo and copy the skill folder into your local skills directory:

git clone https://github.com/Tasdax123/claude-fidelity-translator.git
cp -r claude-fidelity-translator/plugins/fidelity-translator/skills/fidelity-translator \
      ~/.claude/skills/

Dependencies

Either install path needs the following on the machine that runs the skill:

pip install python-docx pyyaml langdetect sentence-splitter
# Also required on PATH: pdfinfo, pdftotext, pdfimages (from poppler-utils)

• macOS: brew install poppler
• Debian / Ubuntu: apt-get install poppler-utils
• Windows: install poppler from https://github.com/oschwartz10612/poppler-windows

First-run setup

In your project directory, create a minimal project.yaml:

project: my-project
domain: aerospace          # or pharma, medical-device, legal, automotive, nuclear, general
target_language: en        # ISO 639-1; source is auto-detected
glossary: ./glossary.md
output_dir: ./translations/

That's it. The skill prompts for anything missing.

Recommended day-one move: bootstrap your glossary

If you have any existing bilingual document pair — one source document and its already-translated counterpart, from any prior translator or tool — run the bootstrap before your first new translation:

"Bootstrap my project glossary from <source.pdf> and <target.pdf>"

The skill will sentence-align the pair, extract terminology pairs via Opus, and pre-populate your glossary in 5–10 minutes at a cost of $1–3. From the very first new translation, you inherit the terminology decisions that pair encodes — solving the cold-start problem in one shot.

What makes this different from a generic LLM translation

Most LLM translation tools optimise for one thing: producing fluent target-language output. That is the wrong objective for regulated documentation. A pharmaceutical IFU that reads beautifully but renders the active substance two different ways across pages is unusable. An aviation manual where chapter 4's "shall" became "should" by chapter 9 fails its review.

fidelity-translator is built around five mechanisms that generic translation tools do not have:

1. A learning glossary that grows with every document

Before any chunk of text gets sent to the translator, the skill scans it for every term that has an entry in the project's glossary. Those source-term → target-term pairs are pinned to the top of the chunk as a mini-table. The translator sees both the glossary anchor and the surrounding context.

This is the single biggest lever on terminology consistency. After the first run on a new product line, every subsequent document inherits the terminology decisions made on the first. After 10 runs you have a glossary that is actually specific to your product, your regulatory tradition, and your reviewer's vocabulary preferences.

2. Self-critique on safety-critical content

For chunks containing WARNING / CAUTION / DANGER callouts, operating limits, emergency procedures, modal-verb clauses in legal text, or pharmaceutical dosage instructions, the skill runs a second pass: a critique subagent reads both the source and the draft translation and is asked specifically to find meaning drift, modal-verb downgrades, or numerical / categorical errors. Any corrections it surfaces are applied by a refine subagent.

This costs about 15 % more in tokens. It catches the class of error that hurts most.

3. Back-translation verification with semantic similarity

For the same safety-critical chunks, the skill round-trips the target back into the source language (using a cheaper, fluency-tuned model) and computes an embedding-similarity score between the original and the back-translation. Below 0.85, the chunk is flagged for human review.

Borrowed from professional translation practice: round-trip stability is one of the most reliable signals of meaning preservation.

4. Deterministic verification — no LLM in the loop

After translation, a pure-regex pass checks every chunk for five things:

• Every section number (02.1.3, 4.5.7.2) in the source appears in the target
• Every numerical value is preserved (with locale-aware date and decimal conversion)
• Every figure / table cross-reference is preserved across the language switch
• Every regulatory citation (§, Art., No., №, FAR, EASA, ISO, IEC, ICH, STANAG patterns) is preserved
• The count AND ordered sequence of WARNING / CAUTION / NOTE callouts in the source matches the target — catching per-callout category swaps even when global counts balance

These are zero-cost (no API calls) and catch the class of error LLMs are most prone to: dropping a section, transposing two callouts, losing a number.

5. Cold-start solved — bootstrap a project glossary from one existing bilingual pair

The biggest barrier to consistency in any translation pipeline is the empty-glossary problem on day one. Generic LLM translation gives you generic-LLM-quality output until you've built up a glossary, which means a lot of human review on the first few documents before the consistency gains kick in.

fidelity-translator solves this on day one if you have any existing translation pair. On first run, the skill offers to mine the pair: it sentence-aligns the two documents deterministically (Gale-Church length-ratio, the same algorithm professional CAT tools have used for three decades), then asks Opus to extract terminology pairs from the aligned segments. The output is 100–400 proposed glossary entries from a typical 200-page pair (cost: $1–3 in API calls), surfaced through the same review flow the skill uses after every translation.

As a side effect, the bootstrap can also export a TMX file for import into Trados, MemoQ, or OmegaT — so the bilingual data goes both into the skill's glossary and into your team's existing CAT workflow.

Plus: an explicit "skill is firing" preflight

Every run begins with a structured banner that names the skill, summarises what it will do, estimates cost and wall-time, and waits for confirmation. The user always knows when this skill is engaged versus when Claude is doing generic translation, and they always have a chance to cancel before a multi-document job racks up tokens.

Industries it ships defaults for

Each domain ships a seed glossary, a hazard-callout mapping, and a register guideline. Pick one in project.yaml or let the skill prompt you at first run.

Languages it ships defaults for

Tested and tuned: English ↔ Ukrainian, German, French, Spanish, Mandarin (Simplified), Japanese, Korean, Portuguese (BR + PT).

Other pairs work — the architecture is language-agnostic — with reduced terminology coverage in the default seeds. Adding a new pair is a 30-minute job: hazard mapping + chapter regex + (optional) glossary seed. See SKILL.md "Adding a new language pair".

How a run looks

▶ Using fidelity-translator (safety-critical document translation)

Translating: aircraft_FOM.pdf (312 pages, ~78,000 words, 287 images)
Direction: uk → en  (auto-detected from Cyrillic + UA markers, conf=0.97)
Domain: aerospace  (from project.yaml)
Glossary: ./glossary.md  (143 existing terms)

What I'll do:
1. Extract text and images; detect chapter boundaries
2. Pin glossary terms per chunk before translation
3. Translate chapter-by-chapter with Opus 4.6, parallel subagents
4. Self-critique pass on safety-critical chunks (callouts, limits, emergencies)
5. Cross-reference against glossary; propose new term additions for review
6. Deterministic verification + back-translate safety-critical chunks (Sonnet 4.6)
7. Assemble Word document in ./translations/ (Times New Roman, monochrome)
8. Append new term proposals to glossary__proposals.md

Estimated cost: ~$12 (Opus translation) + ~$2 (image labels)
Estimated wall time: ~14 minutes

Reply "go" to proceed.

Twelve minutes later you have:

• translations/aircraft_FOM__uk_to_en.docx — the translated document, Times New Roman, bordered tables, monochrome callouts with hazard icons, original engineering diagrams embedded with target-language label tables underneath each one
• translations/aircraft_FOM__uk_to_en__verification.json — full deterministic-check report
• translations/aircraft_FOM__uk_to_en__glossary_proposals.md — new terms surfaced during the run, with per-chunk vote counts on conflicts, ready for your review

What this skill does NOT do (and why)

• It does not produce certified or sworn translations. Every output carries a disclaimer. If you need legal certification, hand the output to a certified translator as a working draft.
• It does not auto-merge glossary proposals. Terminology decisions are yours.
• It does not block on verification failures. The verification report is informational. Some failures are false positives. Humans decide.
• It does not OCR scanned PDFs. OCR quality varies and bad OCR poisons everything downstream. Use tesseract / paddleOCR / ABBYY first.
• It is not for creative or marketing translation. The register is wrong for that.

Origin

This skill was forged on real Ukrainian-to-English aerospace regulatory documents — Flight Operations Manuals, Maintenance Manuals, and certification dossiers for an unmanned aircraft platform — and has been generalised since. The architecture turned out to be domain-agnostic. The original internal version assumed one language pair, one industry, and one company's house style. The generic version (this repo) keeps the architecture and discards the assumptions. The first principle — terminology consistency through a learning glossary — is the same whether you're translating a UAS manual into English or an MDR risk file into German.

Roadmap

See IMPROVEMENTS.md for the v0.2 / v0.3 plan — TMX import (v0.1 already does export), COMET-based quality scoring, MQM-structured critique, OCR fallback for scanned PDFs, bilingual review PDF, tracked-changes DOCX → glossary learning loop, multi-provider consensus for ultra-critical content, and more.

Contributing

See CONTRIBUTING.md. The highest-leverage contributions are new domain × language-pair seed glossaries and support for additional language pairs.

License

MIT.