Translating legacy French docs to English with DeepL and GPT-4o

Core workflow: A semi-automated translation pipeline pairing machine translation (DeepL) and style proofreading (GPT-4o) with strict human oversight via granular Git hunk reviews (git add -p). Automation absorbs the mechanical burden; human judgment validates accuracy and tone.

1. French Markdown corpus
↓ →
2. DeepL raw translation
↓ →
3. Structural cleanup
↓ →
4. GPT-4o style proofreading
↓ →
5. Selective Git review (git add -p)
↓ →
6. Astro build & media fixes
↓ →
7. Next file / human final check

Translating large sets of legacy documentation is always a challenge. Professional human translation ensures quality, but it’s time-consuming and costly, especially when dealing with dozens or even hundreds of Markdown files, diagrams, and embedded metadata.

For my Redaction Technique legacy website, I set up an AI-based iterative workflow that automates much of the heavy lifting while still leaving space for human refinement.

Plastic colorful springs illustrating iterative workflows — Iterative workflow: combining AI translation passes with human-supervised verification loops.

Like most efficient processes, it relies on iteration: a loop that combines different AI tools to enable steady, incremental publishing. Human intervention remains critical at every stage: guiding the process, correcting errors, and keeping the results on track.

The pipeline addresses two fundamentally different types of translation defects:

Language & Style Defects

Addressed by DeepL + GPT-4o

Literal idioms, awkward syntax, passive voice, and phrasing drift. DeepL provides raw sentence conversion, while GPT-4o refines idiom and technical clarity.

Document Structure Defects

Addressed by manual checks & builds

Damaged Markdown table pipes, altered Astro frontmatter delimiters, and broken relative paths. Resolved through explicit formatting passes and local Astro builds.

1. Automatic translation with DeepL

Phase 1: Raw machine translation

The first step is to generate raw English translations of all French Markdown files. A Python script automates this filesystem transformation:

Scans the repository directory for French .md files.
Sends the body content to the DeepL API for French-to-English translation.
Saves the output into a new file with the suffix -en.md.

*.md (French source)
↓ →
Python + DeepL API
↓ →
*-en.md (Raw English draft)

This produces usable English content quickly, but the raw results typically contain broken Markdown tables, mismatched frontmatter, or literal phrasing that sounds unnatural in English technical documentation.

2. Manual structural cleanup of broken Markdown

Before passing files to an LLM, fix structural syntax issues in the raw translated Markdown:

Table delimiters: DeepL frequently inserts or removes pipe characters (|) or wraps table lines irregularly.
Astro YAML frontmatter: Ensure metadata blocks retain valid YAML syntax (title, description, tags).
Formatting quirks: Realign code fences and blockquote markers.

Cleaning syntax at this stage ensures the file builds without errors and prevents the subsequent LLM prompt from misinterpreting corrupted table cells.

3. AI proofreading with GPT-4o

Phase 2: Stylistic refinement

DeepL produces functional translations, but the tone often lacks idiomatic polish. A second Python script passes the cleaned English file to GPT-4o using a tightly constrained technical editing prompt:

GPT-4o Technical Editing Prompt

You are an expert technical writing editor. The text is about technical writing, DITA, and structured authoring. Fix inconsistencies, unprofessional style, and poor French-to-English translations. Keep Markdown formatting intact. Return only the corrected text, without explanations.

The prompt establishes four vital operational guardrails:

Persona & domain: Directs the model to write like a seasoned technical communicator specializing in DITA and structured authoring.
Targeted scope: Instructs it to repair clumsy French-to-English calques and passive phrasing.
Format preservation: Strictly forbids altering Markdown tags, headers, lists, or code fences.
No conversational padding: Prohibits preambles or explanations, returning pure Markdown ready for diffing.

The one-file-at-a-time guardrail: The Python script deliberately processes one file at a time and halts. Pausing after each document creates an indispensable human review boundary, preventing hallucinations or formatting drift from accumulating invisibly across the corpus.

4. Selective review with Git

Phase 3: Human verification

Rather than blindly accepting the LLM’s revisions, review edits selectively using Git’s interactive patch mode:

git add -p

Git displays each modification hunk by hunk, allowing you to accept or discard changes with single-keystroke precision:

Command	Action	Role in Translation Pipeline
`y`	Stage hunk	Accept the AI-suggested translation improvement
`n`	Skip hunk	Reject the suggestion; keep the original DeepL text
`s`	Split hunk	Break compound changes into smaller, independent review units
`e`	Edit hunk	Manually refine the diff in your editor before staging
`q`	Quit	Exit interactive review; leave remaining hunks unstaged

Interactive Git hunk review (git add -p) Diff

diff --git a/communication-technique.md b/communication-technique.md
index d5b0c9b8..7a5632af 100644
--- a/communication-technique.md
+++ b/communication-technique.md
@@ -1,31 +1,30 @@
-The goal of technical communication is to turn prospects into
+The goal of technical communication is to convert prospects into
 satisfied customers. The technical writer provides the market with
(1/1) Stage this hunk [y,n,q,a,d,s,e,p,?]?

This workflow gives you complete authority over what enters your commit history. Storing content in plain files rather than a database makes this granular review fast and transparent.

Once you have staged your approved hunks, commit them:

git commit -m "docs: proofread communication-technique with GPT-4o"

Discard any remaining rejected experiments with:

git reset --hard

5. Build the Astro site and fix translated media

When the English prose is validated, build the Astro site locally to verify linking and asset integrity:

pnpm run build

The build process surfaces remaining asset issues:

Filename synchronization: Update translated image filenames to match English slugs.
Diagram localization: Copy SVG diagrams from fr/ into the corresponding en/ folder.
Vector graphic translation: Edit diagram text labels manually in Inkscape and export updated SVG assets.
Asset paths: Update Markdown image links to reference the newly translated English SVGs.

6. Iterating through the full documentation set

With the workflow established, iterate through the entire corpus file by file:

1. Run proofreading script on next Markdown file
↓
2. Review changes hunk by hunk with git add -p
↓
3. Commit accepted edits & discard rejected noise
↓
4. Run local Astro build & verify rendering
↓
5. Adjust media and SVG diagram assets in Inkscape
↺
Back to next Markdown file — the cycle repeats for each document in the corpus

Pragmatic quality tiering: This workflow is not an uncritical replacement for professional human translation. For legacy or low-traffic technical archives, it provides a cost-effective modernization pipeline where minor stylistic imperfections are acceptable. For high-visibility or customer-facing pages, plan a final round of thorough human proofreading once traffic data validates the investment.

This pipeline lets you modernize a large corpus of technical documentation efficiently by combining the strengths of DeepL, GPT-4o, and deliberate human oversight. For a broader AI-driven approach to working with large content archives, see transforming a corpus of 7,000 pages into living knowledge.

Workflow Takeaways

Human-in-the-loop control: AI drafts and polishes; the technical writer retains absolute veto power through git add -p hunk reviews.
Two-stage translation: DeepL delivers fast initial vocabulary conversion; GPT-4o elevates phrasing to professional technical English.
Structural integrity first: Repair Markdown tables and Astro frontmatter before running LLM editing prompts.
Single-file safety boundary: Processing one document at a time prevents hallucinations or formatting quirks from propagating silently.
Media requires separate care: Translating text is only half the job; diagrams and SVG labels require manual Inkscape editing.
Pragmatic ROI: Enables economical translation of legacy docs while reserving human editorial budgets for high-traffic assets.

Translation — keeping source and translated versions in sync over time.
Transforming a corpus of 7,000 pages into living knowledge — processing large content archives with AI.

External sources

Hero image: “British Museum: Rosetta Stone close ups” by moorina, licensed under CC BY 2.0.