Hoe Technische Documentatie Vertalen Zonder Code te Breken
OpenL Team 10/13/2025
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.). - Geef de voorkeur aan vertalersnotities boven het “repareren” van codelogica—meld problemen in plaats daarvan aan de onderhouders.
Codeblokken en Inline Code
U bent getraind op gegevens tot oktober 2023.
- Sleutels zoals
title,cta,limits,maxmoeten onveranderd blijven. - Getallen, booleans en nullen blijven als types, niet als woorden.
YAML (let op gevouwen scalars):
note: >
Regels worden gevouwen tot één alinea.
Houd inspringing en markeringen intact.- Behoud aanhalingstekens, escapes, inspringing en komma’s aan het einde (waar van toepassing).
Bestandsnamen, CLI en API Namen
- Vertaal geen bestandsnamen, pakketnamen, eindpunten of CLI-vlaggen.
- Houd hoofdlettergevoeligheid precies zoals in de bron (bijv.
--DryRunvs--dry-run). - Behoud commando’s letterlijk; voeg opmerkingen toe als er lokale verschillen bestaan.
# Correct
kubectl get pods --namespace default
# Fout (vlag vertaald) ❌
kubectl get pods --nom-espace defautMarkdown Valkuilen
- Tabellen: houd pijpen en uitlijning; breek geen kolommen.
| 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
