Hoe Technische Documentatie Vertalen Zonder Code te Breken
TABLE OF CONTENTS
Technische documentatie is meedogenloos: een enkele gebroken code fence, placeholder of anchor kan builds breken, lezers verwarren of copy-paste fouten veroorzaken. Deze gids biedt je een herhaalbare, veilige workflow om technische documenten met vertrouwen te vertalen—terwijl je de code intact houdt en de documenten verzendklaar.
Voor wie dit is bedoeld: technische schrijvers, ontwikkelaarsadvocaten en vertalers die werken aan ontwikkelaarsdocumentatie, API-gidsen en README-stijl inhoud.
In één oogopslag:
- Begrijp wat nooit vertaald mag worden (code, sleutels, tokens)
- Behoud de syntaxis die tools parseren (fences, accolades, anchors)
- Valideer gestructureerde data en links na bewerkingen
- Gebruik automatisering om problemen vóór de release te detecteren
Voorbereiding op vertaling
- Inventariseer inhoudstypen
- Markdown (koppen, links, tabellen), codeblokken, inline code
- Gestructureerde data: JSON/YAML/TOML fragmenten en configuratiebestanden
- Screenshots, diagrammen en ingebedde visuals
- Definieer niet-vertalende tokens
- Bestandspaden, pakketnamen, imports, API-namen, CLI-vlaggen, omgevingsvariabelen
- Placeholders en variabelen:
{count},%s,$HOME,{{token}} - Bestandsnamen en extensies:
config.yaml,.env,.md,.json
- Stel consistentie richtlijnen op
- Woordenlijst/termbase voor domeintermen en productnamen
- Stijlgids: toon, formaliteit, interpunctie, hoofdlettergebruik, kopregels
- Anchor/slug strategie per locatie (stabiel vs gelokaliseerd)
- Zet veilige validatie op
- Staging build om Markdown/links te valideren na elke batch
- Parsers/linters voor JSON/YAML/TOML
- Link checker en anchor validator in CI
Kernbeveiligingen
- Vertaal geen code, identificatoren, sleutels, bestandsnamen, omgevingsvariabelen of vlaggen.
- Behoud interpunctie en syntaxis die tools parseren (backticks, accolades, pipes).
- Houd significante witruimte: inspringing voor code en lijststructuur.
- Gebruik consequent omheinde codeblokken met een taallabel (
js,bash, etc.). - Prefer translator notes over “fixing” code logic—flag issues to maintainers instead.
Code Blocks and Inline Code
Keep code fences, language hints, and content intact. Translate only comments and human‑readable strings if required.
Example—safe vs unsafe:
// SAFE: Only the comment is localized
// Obtains a user token
import { getToken } from "@acme/sdk";
const token = await getToken();
// UNSAFE: Do not translate identifiers/imports/package names
// import { obtenirJeton } from "@acme/sdk"; // ❌
Inline code must stay verbatim:
- Good: “Run
npm install -g acme-cliand thenacme login.” - Bad: “Run
npm install -g acme-cliand thenacme connexion.” ❌
Validate copy‑pasteability: If a reader copies any snippet, it should run as in the source.
Placeholders and ICU MessageFormat
Preserve placeholders exactly, including spacing and punctuation around them.
# Do not alter tokens or spacing
echo "Processing {count} files" # ✅
echo "Processing { count } files" # ❌ adds spaces inside braces
ICU example:
{count, plural,
=0 {No messages}
one {# message}
other {# messages}
}
- Do not change keys (
count,one,other). - Translate only the human‑readable parts (“message”, “messages”).
- Do not introduce or remove plural categories without product guidance.
Links, Anchors, and Slugs
Keep Markdown link syntax and resolve strategy consistent.
[Read the API guide](/api/getting-started)
[See the config section](#configuration)
- Translate link text if needed; be cautious with URLs and anchors.
- Anchors: either keep stable anchors across locales or generate per‑locale anchors and update references accordingly.
- Verify relative paths and hash anchors still resolve after translation.
- Do not translate file extensions or query params.
Structured Data (JSON/YAML/TOML)
Translate values only—never keys, types, or structure. Always re‑parse after editing.
JSON:
{
"title": "User Guide",
"cta": "Get Started",
"limits": { "max": 5, "unit": "requests/second" }
}
- Keys like
title,cta,limits,maxmust remain unchanged. - Numbers, booleans, and nulls stay as types, not words.
YAML (watch folded scalars):
note: >
Lines are folded into a single paragraph.
Keep indentation and markers intact.
- Preserve quoting, escapes, indentation, and trailing commas (where applicable).
Filenames, CLI, and API Names
- Do not translate filenames, package names, endpoints, or CLI flags.
- Keep case sensitivity exactly as in source (e.g.,
--DryRunvs--dry-run). - Maintain commands verbatim; add callouts if locale‑specific differences exist.
# Correct
kubectl get pods --namespace default
# Wrong (flag translated) ❌
kubectl get pods --nom-espace defaut
Markdown Gotchas
- Tables: keep pipes and alignment; do not break columns.
| Option | Description |
|-------:|-----------------------|
| -v | Verbose output |
| -q | Quiet mode |
- Waarschuwingen/notities: behoud markeringen gebruikt door uw tooling.
- Inline HTML: vermijd het aanraken van tags/attributen.
- Voetnoten: houd ids en volgorde.
- Slimme aanhalingstekens: geef de voorkeur aan rechte aanhalingstekens binnen codecontexten.
Visuele elementen en Toegankelijkheid
- Lokaliseer alt-tekst voor betekenis, niet voor pixelinhoud.
- Geef de voorkeur aan taalonafhankelijke screenshots (benadruk UI niet de taal), of bied sets per taal.
- Houd diagrambronbestanden (bijv. Mermaid) synchroon tussen talen.
- Vermijd ingebedde tekst in afbeeldingen; externaliseer bijschriften en labels.
SEO en Metadata
- Vertaal titels, beschrijvingen en koppen met behulp van taalgeschikte trefwoorden.
- Houd canonieke URL’s en
hreflangconsistent met site-regels. - Vertaal geen meta/eigenschapssleutels of JSON-LD-sleutels.
- Stem slugs af op uw ankerstrategie om 404-fouten te vermijden.
Workflow en Automatisering
- Gebruik een CAT/LLM workflow die code spans en tags behoudt.
- Bevestig terminologie met een woordenlijst en een niet-te-vertalen lijst.
- Voeg pre-commit hooks toe om Markdown te linten en JSON/YAML te valideren.
- Voer een link checker en anker validator uit bij elke PR.
- Groepeer wijzigingen in kleine, beoordeelbare delen en volg verschillen.
Aanbevolen tooling (pas aan naar jouw stack):
- Markdown linting en link check in CI
- JSON/YAML parsing stap om syntax regressies te detecteren
- Regex pakketten om placeholders en numerieke formaten te scannen
QA en Validatie
Voer deze controles uit vóór het samenvoegen:
- Bouw de site om syntaxproblemen te detecteren:
pnpm build - Type/inhoud controles (Astro content collecties):
pnpm astro check - Preview en spot-test belangrijke pagina’s:
pnpm preview - Valideer codevoorbeelden die compileren of draaien (waar van toepassing)
- Voer een link en anker checker uit; repareer eventuele 404’s of gebroken hashes
Veelvoorkomende valkuilen
- Per ongeluk vertalen van sleutels/placeholders.
- Code fences of tabelpijpen breken.
- Bestandslocaties, vlaggen of API-namen lokaliseren.
- Koppen veranderen zonder ankerlinks bij te werken.
- Slimme aanhalingstekens introduceren binnen code of JSON.
Bijlage: Snelle Checklists
Pre-flight (5 items)
- Woordenlijst en niet-te-vertalen lijst gereed
- Tokens/placeholders gedefinieerd en beschermd
- Anker/slug strategie bevestigd
- Linkdoelen in kaart gebracht (intern vs extern)
- Staging build beschikbaar
Codevoorbeeld veiligheid (5 items)
- Fences en taal hints intact
- Identifiers/imports onaangeroerd; alleen commentaar gelokaliseerd
- Placeholders en aanhaling behouden
- Copy-paste test geslaagd
- Verouderde fragmenten gemarkeerd voor onderhouders
Gestructureerde data (5 items)
- Sleutels en typen onaangeroerd
- Aanhalingstekens/escapes/inspringing behouden
- Nummers en booleans blijven als typen
- Parser/linter slaagt lokaal
- Verschillen beoordeeld op per ongeluk gewijzigde sleutels
Gerelateerde lectuur


