# 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.
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](https://redaction-technique.org/dita-xml-to-markdown-lightweight-information-typing), diagrams, and embedded metadata.
For my [Redaction Technique legacy website](https://docs.redaction-technique.org/), I set up an **AI-based iterative workflow** that automates much of the heavy lifting while still leaving space for human refinement.
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:
Literal idioms, awkward syntax, passive voice, and phrasing drift. DeepL provides raw sentence conversion, while GPT-4o refines idiom and technical clarity.
Damaged Markdown table pipes, altered Astro frontmatter delimiters, and broken relative paths. Resolved through explicit formatting passes and local Astro builds.
## 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
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
```text
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:
1. **Persona & domain:** Directs the model to write like a seasoned technical communicator specializing in DITA and structured authoring.
2. **Targeted scope:** Instructs it to repair clumsy French-to-English calques and passive phrasing.
3. **Format preservation:** Strictly forbids altering Markdown tags, headers, lists, or code fences.
4. **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:
```bash
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](https://redaction-technique.org/manage-content-in-files-not-databases) makes this granular review fast and transparent.
Once you have staged your approved hunks, commit them:
```bash
git commit -m "docs: proofread communication-technique with GPT-4o"
```
Discard any remaining rejected experiments with:
```bash
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:
```bash
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:
**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](https://redaction-technique.org/transforming-corpus-ai-living-knowledge).
---
## Related reading
- [Translation](https://docs.redaction-technique.org/en/tech-writing-process/translation/) - keeping source and translated versions in sync over time.
- [Transforming a corpus of 7,000 pages into living knowledge](https://redaction-technique.org/transforming-corpus-ai-living-knowledge) - processing large content archives with AI.
## External sources
- [DeepL API for raw machine translation](https://www.deepl.com/docs-api)
- [OpenAI/GPT-4o documentation](https://platform.openai.com/docs)
- [git add -p for hunk-by-hunk selective review](https://git-scm.com/docs/git-add)
*Hero image: ["British Museum: Rosetta Stone close ups"](https://www.flickr.com/photos/moorina/3126851416) by [moorina](https://www.flickr.com/photos/moorina/), licensed under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).*
---
Source: https://redaction-technique.org/ai-translation-legacy-technical-docs