Hoe Markdown-documentatie voor ontwikkelaars te vertalen

Spaans (es/README.md):

Raadpleeg de [Installatiegids](./installatie.md) voor configuratie-instructies.

Bekijk de [API-referentie](./referentie-api.md) voor gedetailleerde documentatie.

Kritisch:

• Linktekst vertaald
• Link-URL bijgewerkt naar Spaanse bestandsnaam
• Spaanse bestanden moeten daadwerkelijk bestaan!

Stap 5: Commit naar Git

git add docs/es/
git commit -m "Add Spanish translation of installation docs"
git push origin main

Het omgaan met speciale gevallen

1. Code-opmerkingen in codeblokken

Moet je opmerkingen vertalen?

## Voorbeeld

```javascript
// Initialiseer de applicatie
const app = createApp();

// Start de server op poort 3000
app.listen(3000);

**Optie A: Houd code-opmerkingen in het Engels**
```javascript
// Initialize the application
const app = createApp();

// Start the server on port 3000
app.listen(3000);

Voordelen: Universeel (ontwikkelaars lezen Engelse opmerkingen) Nadelen: Minder toegankelijk voor beginners

Optie B: Vertaal code-opmerkingen

// Applicatie initialiseren
const app = createApp();

// Server starten op poort 3000
app.listen(3000);

Voordelen: Toegankelijker voor niet-Engelstalige ontwikkelaars Nadelen: Code is niet meer direct kopieerbaar (mix van talen)

Aanbeveling: Houd Engels voor productiecode-voorbeelden. Vertaal voor tutorial/leren-inhoud waar begrip > kopiëren-plakken.

2. Variabelen- en functienamen

Nooit vertalen in code:

// FOUT - Niet vertalen variabelennamen
function verkrijgGebruiker(gebruikerId) {
  return database.zoek(gebruikerId);
}

// GOED - Houd code in het Engels
function getUser(userId) {
  return database.find(userId);
}

Uitzondering: Pseudocode of conceptuele voorbeelden

Engels:

if user is logged in: show dashboard else: redirect to login

Nederlands (acceptabel voor pseudocode):

als gebruiker is ingelogd: toon dashboard anders: doorsturen naar login

3. Opdrachtregelvoorbeelden

Vertaal beschrijvingen, niet commando's:

Engels:
## Genereer een Nieuw Component

Gebruik de CLI om een component te maken:

```bash
npx create-component MyComponent

Dit creëert een nieuw component in src/components/MyComponent/.

Nederlands:

Nieuw Component Genereren

Gebruik de CLI om een component te maken:

npx create-component MyComponent

Dit creëert een nieuw component in src/components/MyComponent/.

**Commando's blijven Engels, uitleg vertalen.**

### 4. API-eindpunt-URL's

**Houd URL's ongewijzigd:**

```markdown
Engels:
### Gebruikersprofiel Ophalen

GET /api/v1/users/:id

Nederlands:
### Gebruikersprofiel Ophalen

GET /api/v1/users/:id

Niet: `GET /api/v1/gebruikers/:id` (zou de API breken!)

5. Omgevingsvariabelen en configuratie

Houd variabelennamen, vertaal beschrijvingen:

Engels:
Stel je API-sleutel in:

```bash
export API_KEY=your_key_here

Nederlands: Configureer je API-sleutel:

export API_KEY=jouw_sleutel_hier

API_KEY blijft Engels (omgevingsvariabelenaam). your_key_here → jouw_sleutel_hier (voorbeeldwaarde, kan vertalen).

### 6. Badge-links en shields

**Veelvoorkomend in README.md-bestanden:**

```markdown
Engels:
[![Build Status](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)
[![npm version](https://badge.fury.io/js/awesome-lib.svg)](https://www.npmjs.com/package/awesome-lib)

Nederlands: Houd badges zoals ze zijn
(Ze zijn automatisch van externe services, taal-onafhankelijk)

Of als je vertaalde tekst-badges wilt:
[![Build Status](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)

Meestal: Houd Engelse badges (ontwikkelaars verwachten ze, status is universeel).

Automatisering en tooling

Vertalingbeheersystemen voor Markdown

1. Crowdin

Functies:

• GitHub/GitLab-integratie
• Markdown-bestandsondersteuning
• Behoudt codeblokken automatisch
• Communityvertaling (bijdragers vertalen via web-UI)
• Vertaalgeheugen

Workflow:

1. Verbind Crowdin met GitHub-repo
2. Crowdin detecteert nieuwe/gewijzigde bestanden in docs/en/
3. Vertalers vertalen via Crowdin-webinterface
4. Crowdin dient pull request in met vertalingen
5. Controleer en merge

Prijs: Gratis voor open-source, $40/maand+ voor commercieel

2. Lokalise

Functies:

• Vergelijkbaar met Crowdin
• Betere API voor automatisering
• Markdown-ondersteuning
• CLI-tool voor sync

Workflow:

# Upload bronnenvbestanden
lokalise2 file upload --lang-iso en --file docs/en/README.md

# Download vertalingen
lokalise2 file download --lang-iso nl --dest docs/nl/

Prijs: $120/maand+

3. Transifex

Functies:

• Open-source vriendelijk
• Markdown-ondersteuning
• Vertaalbeoordelingen
• Kwaliteitscontroles

Prijs: Gratis voor open-source, $30/maand+ voor commercieel

Git-gebaseerde vertaalworkflows

Aanpak: Afzonderlijke branches voor vertalingen

# Hoofdbranch: Engelse documentatie
git checkout main

# Maak vertaalbranch aan
git checkout -b translate/spanish

# Vertaal bestanden
# ...

# Commit
git add docs/es/
git commit -m "Voeg Spaanse vertaling toe"

# Push en maak PR aan
git push origin translate/spanish
# Open pull request op GitHub

Voordelen:

• Vertalers werken onafhankelijk
• Reviewproces via PR
• Volg vertalingen als features

Aanpak: Vertalingstracking met Git-metadata

en/installation.md:

<!--
Laatst bijgewerkt: 2025-01-25
Vertaling status:
- es: 2025-01-20 (verouderd)
- fr: 2025-01-24 (actueel)
- zh: nog niet begonnen
-->

# Installatie
...

Geautomatiseerd script kan deze commentaren controleren en verouderde vertalingen markeren.

Geautomatiseerde detectie van vertalingsupdates

Script om verouderde vertalingen te detecteren:

import os
from datetime import datetime

def check_translation_status(base_dir="docs"):
    languages = ['en', 'es', 'fr', 'zh']
    base_lang = 'en'

    for lang in languages:
        if lang == base_lang:
            continue

        en_dir = os.path.join(base_dir, base_lang)
        lang_dir = os.path.join(base_dir, lang)

        for file in os.listdir(en_dir):
            if not file.endswith('.md'):
                continue

            en_file = os.path.join(en_dir, file)
            lang_file = os.path.join(lang_dir, file)

            if not os.path.exists(lang_file):
                print(f"⚠️ {lang}/{file} - Niet vertaald")
                continue

            en_modified = os.path.getmtime(en_file)
            lang_modified = os.path.getmtime(lang_file)

            if en_modified > lang_modified:
                print(f"❌ {lang}/{file} - Verouderd (EN bijgewerkt na vertaling)")
            else:
                print(f"✅ {lang}/{file} - Actueel")

check_translation_status()

Uitvoeren als GitHub Action:

# .github/workflows/check-translations.yml
name: Controleer vertalingstatus

on:
  push:
    paths:
      - 'docs/**'

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Controleer vertalingen
        run: python scripts/check-translations.py
      - name: Commentaar op PR
        if: github.event_name == 'pull_request'
        run: |
          python scripts/check-translations.py > translation-status.txt
          gh pr comment ${{ github.event.number }} --body-file translation-status.txt

AI-ondersteunde Markdown-vertaling

AI Trans voor markdown-documentatie:

Functies:

• Behoudt codeblokken automatisch
• Behoudt markdown-syntax
• Houdt links intact
• Snel (vertaal gehele documentatie in minuten)

Workflow:

# Vertaal README.md van Engels naar Spaans
ai-translator translate \
  --input docs/en/README.md \
  --output docs/es/README.md \
  --source en \
  --target es \
  --format markdown

# Batch-vertaal alle bestanden
for file in docs/en/*.md; do
  filename=$(basename "$file")
  ai-translator translate \
    --input "$file" \
    --output "docs/es/$filename" \
    --source en \
    --target es \
    --format markdown
done

Prijs: $10 voor 1M karakters (Standaard) of $50 voor 10M karakters (Business) Gratis Starter Pack: 100.000 karakters om te testen Typische kostenvoorbeelden:

• Kleine documentatie (50K karakters): $0,50
• Middelgrote documentatie (200K karakters): $2
• Grote documentatie (1M karakters): $10

Best practice: AI vertalen → menselijke review → commit

Opbouwen van meertalige documentatiesites

Docusaurus (gebaseerd op React)

Installatie:

npx create-docusaurus@latest my-docs classic
cd my-docs

i18n-configuratie (docusaurus.config.js):

module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr', 'zh'],
    localeConfigs: {
      en: { label: 'English' },
      es: { label: 'Español' },
      fr: { label: 'Français' },
      zh: { label: '中文' }
    }
  },
  // ...
};

Mapstructuur:

docs/
├── intro.md (Engels standaard)
├── installation.md
i18n/
├── es/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (Spaans)
│           └── installation.md
├── fr/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (Frans)
│           └── installation.md

Build:

# Bouw alle talen
npm run build

# Bouw specifieke taal
npm run build -- --locale es

Resultaat: Automatische taalschakelaar, SEO-geoptimaliseerde meertalige site.

VuePress (gebaseerd op Vue)

i18n-configuratie (.vuepress/config.js):

module.exports = {
  locales: {
    '/': {
      lang: 'en-US',
      title: 'My Documentation',
      description: 'Documentation for awesome library'
    },
    '/es/': {
      lang: 'es-ES',
      title: 'Mi Documentación',
      description: 'Documentación para awesome library'
    },
    '/fr/': {
      lang: 'fr-FR',
      title: 'Ma Documentation',


      description: 'Documentatie voor awesome library'
    }
  },
  themeConfig: {
    locales: {
      '/': {
        selectText: 'Talen',
        label: 'Engels',
        nav: [
          { text: 'Handleiding', link: '/guide/' },
          { text: 'API', link: '/api/' }
        ]
      },
      '/es/': {
        selectText: 'Idiomas',
        label: 'Español',
        nav: [
          { text: 'Guía', link: '/es/guide/' },
          { text: 'API', link: '/es/api/' }
        ]
      }
    }
  }
};

**Directory:**

docs/ ├── README.md (Engels) ├── guide/ │ └── installation.md ├── es/ │ ├── README.md (Spaans) │ └── guide/ │ └── installation.md └── fr/ ├── README.md (Frans) └── guide/ └── installation.md

### MkDocs (Python-gebaseerd)

**Installeren met i18n-plugin:**

```bash
pip install mkdocs mkdocs-static-i18n

mkdocs.yml:

plugins:
  - i18n:
      default_language: en
      languages:
        en: English
        es: Español
        fr: Français
      material_alternate: true

nav:
  - Home: index.md
  - Installation: installation.md
  - API Reference: api.md

Directory:

docs/
├── index.md (Engels standaard)
├── index.es.md (Spaans)
├── index.fr.md (Frans)
├── installation.md
├── installation.es.md
├── installation.fr.md

Build:

mkdocs build

Resultaat: Genereert site/ met taalschakelaar.

GitHub Pages Deployment

Multilingual Docusaurus-site deployen:

# .github/workflows/deploy.yml
name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install dependencies
        run: npm install
      - name: Build website
        run: npm run build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Toegang:

• Engels: https://youruser.github.io/yourrepo/
• Spaans: https://youruser.github.io/yourrepo/es/
• Frans: https://youruser.github.io/yourrepo/fr/

Best Practices en Valstrikken

Best Practices

1. Begin met pagina's met hoge impact

Prioriteer:
1. README.md (eerste wat gebruikers zien)
2. Installation/Getting Started (blokkeert adoptie)
3. API Reference (ontwikkelaars hebben dit nodig)
4. Contributing Guide (voor internationale bijdragers)

Overslaan aanvankelijk:
- Changelogs (minder kritisch)
- Verouderde docs
- Interne ontwikkelaarsnotities

2. Houd een vertaalstijlhandleiding aan

# Vertaalstijlhandleiding - Spaans

## Terminologie
- "library" → "biblioteca" (niet "librería" wat boekwinkel betekent)
- "framework" → behoud als "framework" (breed begrepen)
- "deploy" → "desplegar" (niet "implementar")

## Toon
- Gebruik formele "usted" voor technische docs
- Gebruik informele "tú" voor tutorials/handleidingen
- Wees bondig (Spaans is gemiddeld 20% langer dan Engels)

## Code
- Vertaal nooit codeblokken
- Houd technische termen in het Engels als ze breed gebruikt worden

3. Versieer je vertalingen

README.md:
<!--
Translation: Spanish
Source version: v2.5.0
Translated: 2025-01-25
Translator: @username
-->

# Instalación
...

Dit helpt bij het bijhouden wanneer vertalingen achterlopen.

4. Stimuleer bijdragen van de gemeenschap

## Bijdragen aan Vertalingen

We verwelkomen vertalingen! Om bij te dragen:

1. Fork deze repository
2. Maak `docs/[language-code]/` directory
3. Vertaal bestanden van `docs/en/`
4. Dien een pull request in

Vertaalhandleiding: [TRANSLATION.md](./TRANSLATION.md)

Veelvoorkomende Valstrikken

Valstrik 1: Vertalen van URL's en bestandspaden

❌ FOUT:
[Zie installatie](./instalación.md)
# Bestand bestaat niet (heeft accenten)

✅ GOED:
[Zie installatie](./instalacion.md)
# Bestand: instalacion.md (geen accenten in bestandsnaam)

Valstrik 2: Relatieve links breken

Engels: docs/en/guide.md linkt naar: ../assets/image.png
Spaans: docs/es/guia.md moet linken naar: ../assets/image.png (zelfde pad!)

Als Spaanse vertaler schrijft: ./assets/image.png (defect!)

Valstrik 3: Alt-tekst van afbeeldingen vergeten

![](./screenshot.png)

Moet zijn:
![Dashboard screenshot](./screenshot.png)

Spaans:
![Captura de pantalla del panel](./screenshot.png)

Alt-tekst is belangrijk voor toegankelijkheid!

Valstrik 4: Inconsistente terminologie

Pagina 1: "servidor" (server)
Pagina 3: "server" (in Engels gehouden)
Pagina 5: "servidor" weer

Kies er één en houd je eraan! Gebruik een glossarium.

Succes Meten

Te Volgen Metrics

1. Documentatiegebruik per taal

Google Analytics (documentatiesite):
- Verkeer per taal (es, fr, de, etc.)
- Tijd op pagina (hoger = beter begrip)
- Bounce rate (lager voor moedertaal-docs)

Voorbeeld:
Engelse docs: 70% van gebruikers
Spaanse docs: 15% van gebruikers (maar groeiend!)
Franse docs: 10% van gebruikers
Overig: 5%

2. GitHub-inzichten

GitHub Issues:
- Aantal issues ingediend in elke taal
- Reactietijd op niet-Engelstalige issues

Pull Requests:
- Bijdragen uit niet-Engelstalige landen
- Na Spaanse docs: +40% bijdragen van LATAM-ontwikkelaars

Stars/Forks:
- Groei volgen na vertaalreleases

3. Communitygroei

Discord/Slack:
- Activiteit in taal-specifieke kanalen
- Vragen in moedertalen

Stack Overflow:
- Vragen getagd met je bibliotheek in verschillende talen

4. npm/PyPI-downloads per regio

npm downloadstatistieken per land:
Voor Chinese vertaling:
- China: 5% van downloads

Na Chinese vertaling:
- China: 22% van downloads (4,4x groei!)

Kosten en ROI

Vertalingsinvestering

Kleine open-source bibliotheek (5.000 woorden docs):

Professionele vertaling:

Vertaling: 5.000 × $0,08 = $400 per taal
Review: $100
Totaal per taal: $500

3 talen (es, fr, zh): $1.500

AI-ondersteunde vertaling:

AI-vertaling (AI Trans): 5.000 woorden × 6 tekens gem = 30.000 tekens = $0,30
Technische reviewer: 5 uur × $75 = $375
Totaal per taal: $375,30

3 talen: $1.126 (bespaart 25%)

Community-bijdragen (gratis maar langzamer):

Crowdin opzetten: Gratis voor open-source
Vertalingen: Gratis (community-vrijwilligers)
Reviewtijd: Jouw tijd (5-10 uur per taal)

3 talen: $0 monetaire kosten, 15-30 uur tijdsinvestering

ROI voor Open-Source Projecten

ROI is niet altijd monetair—het is communitygroei:

Metrieken voor Spaanse/Chinese vertalingen:
- Maandelijkse npm-downloads: 50.000
- GitHub stars: 2.500
- Bijdragers: 40 (voornamelijk VS/Europa)

6 maanden na vertalingen:
- Maandelijkse npm-downloads: 120.000 (140% groei)
- GitHub stars: 6.800 (172% groei)
- Bijdragers: 95 (55 nieuw uit LATAM/Azië)

Communitywaarde: Onbetaalbaar
Kosten: $1.500 voor AI-ondersteund + review

Tools en Bronnen

Vertalingstools

AI Trans

• Behoudt markdown-opmaak automatisch
• Houdt codeblokken intact (vertalt nooit code)
• Behoudt linkstructuur
• $10 per 1M tekens (Standard) of $50 per 10M tekens (Business)
• Gratis 100K tekens starterpakket
• 57 talen ondersteund

DeepL API

• Hoge kwaliteit voor Europese talen
• Markdown-ondersteuning met preprocessing
• $25 per miljoen tekens + $5,49/maand abonnement

Google Cloud Translation

• 133 talen
• Goed voor brede taaldekking
• $20 per miljoen tekens
• Geen markdown-begrip (vereist preprocessing)

Markdown-linting en validatie

markdownlint

• Valideert markdown-syntax
• Zorgt voor consistente opmaak
• CLI en editor-plugins

npm install -g markdownlint-cli
markdownlint docs/es/*.md

markdown-link-check

• Valideert alle links in markdown-bestanden
• Vangt kapotte relatieve links op

npm install -g markdown-link-check
markdown-link-check docs/es/README.md

Documentatiesitebouwers

Docusaurus (React)

• Beste voor: React-ontwikkelaars, moderne SPA-docs
• i18n ingebouwd
• Gratis

VuePress (Vue.js)

• Beste voor: Vue-ontwikkelaars
• Eenvoudige setup
• Gratis

MkDocs (Python)

• Beste voor: Python-projecten
• Minimale configuratie
• Gratis

GitBook

• Beste voor: Niet-ontwikkelaars (GUI-editor)
• Gehoste oplossing
• Gratis voor open-source

Conclusie

Het vertalen van markdown-documentatie is een van de meest impactvolle bijdragen die je kunt leveren aan de wereldwijde developer-community. Door je project toegankelijk te maken in meerdere talen, ontgrendel je adoptie door miljarden niet-Engelstalige ontwikkelaars en stimuleer je diverse, internationale samenwerking.

Belangrijkste takeaways:

• Behoud codeblokken, markdown-syntax en linkstructuur
• Gebruik aparte directories per taal voor schone organisatie
• Automatiseer vertaal-synchronisatie met Git-workflows
• Gebruik AI-vertaling + menselijke review voor kosteneffectieve kwaliteit
• Bouw meertalige sites met Docusaurus, VuePress of MkDocs
• Volg vertalingen met metadata en geautomatiseerde checks
• Stimuleer community-bijdragen voor duurzame vertaling

Moderne AI-tools zoals AI Trans kunnen vertaalingskosten met 70-90% verminderen terwijl alle kritische markdown-elementen zoals codeblokken, links en opmaak behouden blijven. De optimale workflow: AI vertaalt initiële documentatie (minuten, geen weken), technische reviewers zorgen voor nauwkeurigheid en consistentie, dan helpt de community bij het onderhouden van updates.

Typische documentatievertaalkosten:

• Klein project (50K tekens): $0,50 met AI Trans vs. $400 menselijke vertaling
• Middelgroot project (200K tekens): $2 met AI Trans vs. $1.600 menselijke vertaling
• Groot project (1M tekens): $10 met AI Trans vs. $8.000 menselijke vertaling

Tijdwinst: 95%+ (minuten vs. weken)

Of je nu een kleine utility-bibliotheek onderhoudt of een groot open-source framework, vertaalde documentatie verwijdert taalbarrières en verwelkomt ontwikkelaars wereldwijd in je project.

Klaar om je documentatie te vertalen? Begin met het vertalen van je markdown-docs met de code-behoudende vertaalengine van AI Trans en bereik ontwikkelaars wereldwijd.