AI Trans
Developer Tools

How to Translate Markdown Documentation for Developers

A
Geschrieben von
AI Trans Team
19 Min. Lesezeit
325 Aufrufe

Open-Source-Projekte leben oder sterben durch ihre Dokumentation. Eine brillante Bibliothek mit einem rein englischen README wird niemals Entwickler in China, Japan oder Brasilien erreichen – Märkte, die 40 % der weltweiten Entwicklerbevölkerung repräsentieren. Doch die Übersetzung von Markdown-Dokumentationen ist einzigartig anspruchsvoll: Sie müssen Code-Blöcke erhalten, die Verknüpfungsstruktur beibehalten, Versionskontrolle handhaben und Übersetzungen synchron halten, während sich Ihr Projekt weiterentwickelt.

Laut dem GitHub Octoverse-Bericht 2024 stammen 78 % der Open-Source-Beiträge von Nicht-Muttersprachlern des Englischen, doch 92 % der Dokumentationen bleiben rein englisch. Dies schafft eine massive Barriere für Adoption, Beiträge und den Aufbau globaler Communities.

Dieser umfassende Leitfaden zeigt Ihnen, wie Sie Markdown-Dokumentationen effektiv übersetzen: vom Erhalt der Code-Syntax und Links über die Verwaltung von Übersetzungs-Workflows in Git, automatisierte Updates bis hin zum Aufbau mehrsprachiger Dokumentationsseiten mit Tools wie Docusaurus, VuePress und MkDocs.

Warum Markdown-Dokumentationsübersetzung anders ist

Markdown ist eine Auszeichnungssprache, die für technisches Schreiben entwickelt wurde. Beim Übersetzen von Markdown-Dokumenten übersetzen Sie nicht nur Prosa – Sie verwalten eine komplexe Mischung aus Code, Formatierungssyntax, Hyperlinks, Versionskontrolle und kontinuierlichen Updates.

Die Herausforderung der Markdown-Übersetzung

1. Code-Blöcke dürfen niemals übersetzt werden

## Installation

Führen Sie den folgenden Befehl aus:

```bash
npm install awesome-library

Beim Übersetzen ins Spanische:

  • "Installation" → "Instalación" ✅
  • "Run the following command:" → "Ejecuta el siguiente comando:" ✅
  • npm install awesome-library → UNVERÄNDERT LASSEN ✅

Generische Übersetzer zerstören oft Code durch Übersetzung!


**2. Markdown-Syntax muss erhalten bleiben**

```markdown
**Fetter Text** sollte **fett** bleiben
*Kursiver Text* sollte *kursiv* bleiben
[Link-Text](url) sollte die Link-Struktur beibehalten
`Inline-Code` sollte die Backticks behalten

Schlechte Übersetzung könnte erzeugen:
**Fett** (verliert Markdown-Syntax)
*Kursiv (fehlendes schließendes Sternchen)
[Text](url (defekter Link)

3. Relative Links müssen für Sprachversionen aktualisiert werden

Englisch: [See API Reference](./api-reference.md)
Spanisch: [Ver Referencia API](./referencia-api.md)
         ^Link-Text übersetzt  ^Dateiname ebenfalls übersetzt

Beide müssen existieren und korrekt verlinken!

4. Dokumentation entwickelt sich – Übersetzungen auch

Tag 1: Übersetze README.md (Englisch → Spanisch)
Tag 15: Englische README.md aktualisiert (neue Funktion hinzugefügt)
Problem: Spanische Version ist jetzt veraltet!

Workflow benötigt, um Übersetzungsaktualisierungen zu verfolgen und zu synchronisieren.

Reale Auswirkungen

Erfolgsstory: Vue.js

  • Dokumentation in 10+ Sprachen übersetzt
  • Chinesische Übersetzung entscheidend für Adoption in Asien
  • Community-getriebener Übersetzungs-Workflow über GitHub
  • Ergebnis: 40 % der npm-Downloads aus Asien, massive chinesische Community

Erfolgsstory: React

  • Offizielle Übersetzungen in 30+ Sprachen, verwaltet von der Community
  • Separate Repos für jede Sprache (react.dev, zh-hans.react.dev, es.react.dev)
  • Übersetzungsleitfaden und Automatisierungstools bereitgestellt
  • Ergebnis: Globale Entwickleradoption, Beiträge aus 100+ Ländern

Erfolgsstory: Rust-Programmiersprache

  • "The Rust Book" in 15+ Sprachen übersetzt
  • Community pflegt Übersetzungen über mdBook
  • Japanische Übersetzung führte zu 300 % Zunahme japanischer Rust-Entwickler
  • Aktive Übersetzungsteams halten Docs mit englischen Updates synchron

Misserfolgsfall: Verlassene Übersetzungen Viele Open-Source-Projekte haben veraltete Übersetzungen:

  • Französisches README zuletzt vor 2 Jahren aktualisiert
  • Englische README wöchentlich aktualisiert
  • Ergebnis: Französische Entwickler verwirrt, verlassen Projekt oder kämpfen mit veralteten Infos

Markdown-Grundlagen für Übersetzungen

Kern-Markdown-Elemente

Überschriften:

# Überschrift 1
## Überschrift 2
### Überschrift 3

Text übersetzen, Symbole erhalten:
# Installation → # Installation
## Quick Start → ## Schnellstart

Betonung:

**fetter Text** → **fetter Text**
* kursiver Text* → *kursiver Text*
~~Durchgestrichener Text~~ → ~~durchgestrichener Text~~

Markdown-Syntax exakt beibehalten.

Listen:

Ungeordnet:
- Element eins
- Element zwei
  - Verschachteltes Element

Geordnet:
1. Erster Schritt
2. Zweiter Schritt
3. Dritter Schritt

Inhalt übersetzen, Struktur beibehalten:
- Erstes Element
- Zweites Element
  - Verschachteltes Element

Links:

[Link-Text](url)
[Documentation](https://example.com/docs)

Text übersetzen, URL beibehalten (außer bei Übersetzung der verlinkten Seite):
[Dokumentation](https://example.com/docs)

Oder bei existierenden spanischen Docs:
[Dokumentation](https://example.com/es/docs)

Bilder:

![Alt-Text](bild-url "Optionaler Titel")

![Dashboard-Screenshot](./images/dashboard.png "Admin-Dashboard")

Alt-Text und Titel übersetzen:
![Screenshot des Dashboards](./images/dashboard.png "Administrations-Dashboard")

Dateiname des Bildes bleibt meist gleich (geteilte Ressource).

Code-Blöcke:

Inline-Code: Verwende `npm install`, um Pakete zu installieren.

Übersetze Prosa, bewahre Code: Verwende npm install, um Pakete zu installieren.

Fenced Code-Blöcke:

function greet(name) {
  console.log(`Hello, ${name}!`);
}

NIEMALS Code innerhalb von Zäunen übersetzen. Genau so lassen.


**Tabellen:**
```markdown
| Englisch | Spanisch | Französisch |
|----------|----------|-------------|
| Hello    | Hola     | Bonjour     |
| Goodbye  | Adiós    | Au revoir   |

Inhaltszellen übersetzen, Struktur beibehalten:
| Englisch | Spanisch | Französisch |
|----------|----------|-------------|
| Hello    | Hola     | Bonjour     |
| Goodbye  | Adiós    | Au revoir   |

Erweiterte Markdown-Features

Blockzitate:

> Dies sind wichtige Informationen, die Benutzer wissen sollten.

Inhalt übersetzen, >-Symbol beibehalten:
> Dies sind wichtige Informationen, die Benutzer wissen sollten.

Horizontale Linien:

---
oder
***
oder
___

Unverändert lassen (visueller Trenner, kein Text).

HTML in Markdown:

<div class="warning">
  Sei vorsichtig beim Verwenden dieser Funktion!
</div>

HTML-Tags beibehalten, Inhalt übersetzen:
<div class="warning">
  Sei vorsichtig beim Verwenden dieser Funktion!
</div>

Fußnoten:

Hier ist eine Fußnoten-Referenz[^1].

[^1]: Dies ist der Fußnoteninhalt.

Sowohl Referenzkontext als auch Fußnotentext übersetzen:
Hier ist eine Fußnoten-Referenz[^1].

[^1]: Dies ist der Fußnoteninhalt.

Übersetzungsworkflow für Markdown-Dokumente

Option 1: Separate Dateien pro Sprache (Empfohlen)

Verzeichnisstruktur:

docs/
├── en/
│   ├── README.md
│   ├── installation.md
│   ├── api-reference.md
│   └── troubleshooting.md
├── es/
│   ├── README.md
│   ├── instalacion.md
│   ├── referencia-api.md
│   └── solucion-problemas.md
├── fr/
│   ├── README.md
│   ├── installation.md
│   ├── reference-api.md
│   └── depannage.md
└── zh/
    ├── README.md
    ├── installation.md
    ├── api-reference.md
    └── troubleshooting.md

Vorteile: ✅ Klare Trennung (keine gemischten Sprachen) ✅ Jede Sprache kann unterschiedliche Dateistruktur haben, falls nötig ✅ Einfach zu sehen, welche Dateien übersetzt sind ✅ Einfaches Verlinken innerhalb derselben Sprache

Nachteile: ❌ Schwieriger zu verfolgen, welche Übersetzungen veraltet sind ❌ Mehr Dateien zu verwalten

Option 2: Suffix-basiert (Alternative)

Verzeichnisstruktur:

docs/
├── README.md (Englisch Standard)
├── README.es.md (Spanisch)
├── README.fr.md (Französisch)
├── README.zh.md (Chinesisch)
├── installation.md
├── installation.es.md
├── installation.fr.md
└── installation.zh.md

Vorteile: ✅ Übersetzte Dateien neben der Quelle (einfacher fehlende Übersetzungen zu erkennen) ✅ Alphabetisch nach Basename sortiert

Nachteile: ❌ Wird unübersichtlich bei vielen Sprachen ❌ Schwieriger, sprachspezifische Dokumente zu durchsuchen

Urteil: Separate Verzeichnisse verwenden für Projekte mit umfassender Dokumentation.

Schritt-für-Schritt-Übersetzungsprozess

Schritt 1: Übersetzungsverzeichnisstruktur einrichten

# Sprachverzeichnisse erstellen
mkdir -p docs/es docs/fr docs/zh

# Englische Struktur in neue Sprache kopieren
cp -r docs/en/* docs/es/

# Nun jede Datei in docs/es/ übersetzen

Schritt 2: Übersetzungsverfolgung erstellen

translation-status.md:

# Übersetzungsstatus

## Spanisch (es)

| Datei | Status | Letzte Aktualisierung | Übersetzer |
|-------|--------|-----------------------|------------|
| README.md | ✅ Aktuell | 2025-01-25 | @translator1 |
| installation.md | ⚠️ Veraltet | 2025-01-10 | @translator1 |
| api-reference.md | ❌ Nicht gestartet | - | - |

## Französisch (fr)

| Datei | Status | Letzte Aktualisierung | Übersetzer |
|-------|--------|-----------------------|------------|
| README.md | ✅ Aktuell | 2025-01-22 | @translator2 |
| installation.md | ✅ Aktuell | 2025-01-22 | @translator2 |

Oder automatisierte Tools verwenden (später behandelt).

Schritt 3: Mit Erhaltung von Code-Blöcken übersetzen

Original (en/installation.md):

# Installation

## Voraussetzungen

- Node.js 18+
- npm oder yarn

## Über npm installieren

Führen Sie den folgenden Befehl in Ihrem Terminal aus:

```bash
npm install awesome-library

Installation überprüfen

Erstellen Sie eine Testdatei test.js:

const awesome = require('awesome-library');
console.log(awesome.version);

Führen Sie sie aus:

node test.js

Sie sollten die Versionsnummer ausgegeben sehen.


**Übersetzt (es/instalacion.md):**
```markdown
# Installation

## Voraussetzungen

- Node.js 18+
- npm oder yarn

## Über npm installieren

Führen Sie den folgenden Befehl in Ihrem Terminal aus:

```bash
npm install awesome-library

Installation überprüfen

Erstellen Sie eine Testdatei test.js:

const awesome = require('awesome-library');
console.log(awesome.version);

Führen Sie sie aus:

node test.js

Sie sollten die Versionsnummer ausgegeben sehen.


**Was geändert wurde:**
- Überschriften übersetzt
- Prosa übersetzt
- Code-Blöcke UNVERÄNDERT (bash-Befehle, JavaScript-Code)
- Inline-Code UNVERÄNDERT (`test.js`, npm-Pakennamen)
- Dateistruktur beibehalten

**Schritt 4: Interne Links aktualisieren**

**Englisch (en/README.md):**
```markdown
Siehe [Installationsanleitung](./installation.md) für Einrichtungsanweisungen.

Überprüfe die API-Referenz für detaillierte Dokumentation.

Deutsch (de/README.md):

Siehe [Installationsanleitung](./installation.md) für Einrichtungsanweisungen.

Was geändert wurde:

  • Überschriften übersetzt
  • Fließtext übersetzt
  • Code-Blöcke UNVERÄNDERT (bash-Befehle, JavaScript-Code)
  • Inline-Code UNVERÄNDERT (test.js, npm-Paketnamen)
  • Dateistruktur beibehalten

Schritt 4: Interne Links aktualisieren

Englisch (en/README.md):

Siehe [Installationsanleitung](./installation.md) für Einrichtungsanweisungen.

Deutsch (de/README.md):

Konsultiere die [Installationsanleitung](./installation.md) für Konfigurationsanweisungen.

Überprüfe die [API-Referenz](./api-reference.md) für detaillierte Dokumentation.

Wichtig:

  • Link-Text übersetzt
  • Link-URL an deutschen Dateinamen angepasst
  • Deutsche Dateien müssen tatsächlich existieren!

Schritt 5: In Git committen

git add docs/de/
git commit -m "Füge deutsche Übersetzung der Installationsdokumente hinzu"
git push origin main

Umgang mit Sonderfällen

1. Code-Kommentare in Code-Blöcken

Sollten Kommentare übersetzt werden?

## Beispiel

```javascript
// Initialize the application
const app = createApp();

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


**Option A: Code-Kommentare auf Englisch belassen**
```javascript
// Initialize the application
const app = createApp();

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

Vorteile: Universell (Entwickler lesen englische Kommentare) Nachteile: Weniger zugänglich für Anfänger

Option B: Code-Kommentare übersetzen

// Die Anwendung initialisieren
const app = createApp();

// Den Server auf Port 3000 starten
app.listen(3000);

Vorteile: Zugänglicher für Nicht-Englisch sprechende Entwickler Nachteile: Code ist nicht mehr einfach kopierbar (Sprachmischung)

Empfehlung: Englisch für Produktionscode-Beispiele beibehalten. Übersetzen für Tutorials/Lerninhalte, wo Verständnis > Kopieren.

2. Variablen- und Funktionsnamen

Niemals in Code übersetzen:

// FALSCH - Variablennamen nicht übersetzen
function benutzerHolen(benutzerId) {
  return database.suchen(benutzerId);
}

// RICHTIG - Code auf Englisch belassen
function getUser(userId) {
  return database.find(userId);
}

Ausnahme: Pseudocode oder konzeptionelle Beispiele

Englisch:

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


Deutsch (akzeptabel für Pseudocode):

wenn Benutzer angemeldet ist: Dashboard anzeigen sonst: zu Login weiterleiten

3. Kommandozeilen-Beispiele

Beschreibungen übersetzen, Befehle nicht:

Englisch:
## Generate a New Component

Use the CLI to create a component:

```bash
npx create-component MyComponent

This creates a new component in src/components/MyComponent/.

Deutsch:

Neuen Komponenten generieren

Verwende die CLI, um eine Komponente zu erstellen:

npx create-component MyComponent

Dies erstellt eine neue Komponente in src/components/MyComponent/.


**Befehle bleiben englisch, Erklärungen werden übersetzt.**

### 4. API-Endpunkt-URLs

**URLs unverändert belassen:**

```markdown
Englisch:
### Get User Profile

GET /api/v1/users/:id


Deutsch:
### Benutzerprofil abrufen

GET /api/v1/users/:id


Nicht: `GET /api/v1/users/:id` (würde die API kaputtmachen!)

5. Umgebungsvariablen und Konfiguration

Variablennamen beibehalten, Beschreibungen übersetzen:

Englisch:
Set your API key:

```bash
export API_KEY=your_key_here

Deutsch: Konfiguriere deinen API-Schlüssel:

export API_KEY=dein_schluessel_hier

API_KEY bleibt englisch (Umgebungsvariablenname). your_key_here → dein_schluessel_hier (Beispielwert, kann übersetzt werden).


### 6. Badge-Links und Shields

**Häufig in README.md-Dateien:**

```markdown
Englisch:
[![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)

Deutsch: Badges so belassen
(Sie sind automatisch von externen Diensten, sprachunabhängig)

Oder wenn du übersetzte Text-Badges möchtest:
[![Build-Status](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)

Normalerweise: Englische Badges beibehalten (Entwickler erwarten sie, Status ist universell).

Automatisierung und Tools

Übersetzungsmanagementsysteme für Markdown

1. Crowdin

Features:

  • GitHub/GitLab-Integration
  • Markdown-Dateiunterstützung
  • Code-Blöcke automatisch geschützt
  • Community-Übersetzung (Mitwirkende übersetzen über Web-UI)
  • Übersetzungsspeicher

Workflow:

1. Crowdin mit GitHub-Repo verbinden
2. Crowdin erkennt neue/ändere Dateien in docs/en/
3. Übersetzer arbeiten über Crowdin-Weboberfläche
4. Crowdin erstellt Pull Request mit Übersetzungen
5. Überprüfen und mergen

Preise: Kostenlos für Open-Source, ab $40/Monat für kommerziell

2. Lokalise

Features:

  • Ähnlich wie Crowdin
  • Bessere API für Automatisierung
  • Markdown-Unterstützung
  • CLI-Tool für Synchronisation

Workflow:

# Quelldateien hochladen
lokalise2 file upload --lang-iso en --file docs/en/README.md

# Übersetzungen herunterladen
lokalise2 file download --lang-iso de --dest docs/de/

Preise: ab $120/Monat

3. Transifex

Features:

  • Open-Source-freundlich
  • Markdown-Unterstützung
  • Übersetzungsüberprüfungen
  • Qualitätsprüfungen

Preise: Kostenlos für Open-Source, ab $30/Monat für kommerziell

Git-basierte Übersetzungs-Workflows

Ansatz: Separate Branches für Übersetzungen

# Hauptbranch: Englische Docs
git checkout main

# Übersetzungsbranch erstellen
git checkout -b translate/spanish

# Dateien übersetzen
# ...

# Commit
git add docs/es/
git commit -m "Spanische Übersetzung hinzufügen"

# Push und PR erstellen
git push origin translate/spanish
# Pull Request auf GitHub öffnen

Vorteile:

  • Übersetzer arbeiten unabhängig
  • Review-Prozess über PR
  • Übersetzungen als Features tracken

Ansatz: Übersetzungsverfolgung mit Git-Metadaten

en/installation.md:

<!--
Zuletzt aktualisiert: 2025-01-25
Übersetzungsstatus:
- es: 2025-01-20 (veraltet)
- fr: 2025-01-24 (aktuell)
- zh: nicht gestartet
-->

# Installation
...

Automatisierte Skripte können diese Kommentare prüfen und veraltete Übersetzungen markieren.

Automatisierte Erkennung von Übersetzungsaktualisierungen

Skript zur Erkennung veralteter Übersetzungen:

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} - Nicht übersetzt")
                continue

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

            if en_modified > lang_modified:
                print(f"❌ {lang}/{file} - Veraltet (EN nach Übersetzung aktualisiert)")
            else:
                print(f"✅ {lang}/{file} - Aktuell")

check_translation_status()

Als GitHub Action ausführen:

# .github/workflows/check-translations.yml
name: Übersetzungsstatus prüfen

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

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Übersetzungen prüfen
        run: python scripts/check-translations.py
      - name: Kommentar zu 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

KI-unterstützte Markdown-Übersetzung

AI Trans für Markdown-Docs:

Features:

  • Code-Blöcke automatisch erhalten
  • Markdown-Syntax beibehalten
  • Links intakt lassen
  • Schnell (ganze Dokumentation in Minuten übersetzen)

Workflow:

# README.md von Englisch nach Spanisch übersetzen
ai-translator translate \
  --input docs/en/README.md \
  --output docs/es/README.md \
  --source en \
  --target es \
  --format markdown

# Alle Dateien batch-übersetzen
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

Preise: $10 für 1M Zeichen (Standard) oder $50 für 10M Zeichen (Business) Kostenloses Starter-Paket: 100.000 Zeichen zum Testen Typische Kostenbeispiele:

  • Kleine Docs (50K Zeichen): $0.50
  • Mittlere Docs (200K Zeichen): $2
  • Große Docs (1M Zeichen): $10

Best Practice: KI übersetzen → menschliche Überprüfung → commit

Aufbau multilingualer Dokumentationsseiten

Docusaurus (React-basiert)

Setup:

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

i18n-Konfiguration (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: '中文' }
    }
  },
  // ...
};

Verzeichnisstruktur:

docs/
├── intro.md (English default)
├── installation.md
i18n/
├── es/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (Spanish)
│           └── installation.md
├── fr/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (French)
│           └── installation.md

Build:

# Alle Sprachen bauen
npm run build

# Spezifische Sprache bauen
npm run build -- --locale es

Ergebnis: Automatischer Sprachwechsler, SEO-optimierte mehrsprachige Seite.

VuePress (Vue-basiert)

i18n-Konfiguration (.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: 'Dokumentation für awesome library'
    }
  },
  themeConfig: {
    locales: {
      '/': {
        selectText: 'Sprachen',
        label: 'Englisch',
        nav: [
          { text: 'Anleitung', link: '/guide/' },
          { text: 'API', link: '/api/' }
        ]
      },
      '/es/': {
        selectText: 'Idiomas',
        label: 'Spanisch',
        nav: [
          { text: 'Guía', link: '/es/guide/' },
          { text: 'API', link: '/es/api/' }
        ]
      }
    }
  }
};

**Verzeichnis:**

docs/ ├── README.md (Englisch) ├── guide/ │ └── installation.md ├── es/ │ ├── README.md (Spanisch) │ └── guide/ │ └── installation.md └── fr/ ├── README.md (Französisch) └── guide/ └── installation.md


### MkDocs (Python-basiert)

**Installation mit 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

Verzeichnis:

docs/
├── index.md (Englisch standardmäßig)
├── index.es.md (Spanisch)
├── index.fr.md (Französisch)
├── installation.md
├── installation.es.md
├── installation.fr.md

Build:

mkdocs build

Ergebnis: Erzeugt site/ mit Sprachumschalter.

GitHub Pages Deployment

Multilinguale Docusaurus-Site bereitstellen:

# .github/workflows/deploy.yml
name: Dokumentation bereitstellen

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: Abhängigkeiten installieren
        run: npm install
      - name: Website erstellen
        run: npm run build
      - name: Auf GitHub Pages bereitstellen
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Zugriff:

Best Practices und Fallstricke

Best Practices

1. Mit hochwirksamen Seiten beginnen

Priorisieren:
1. README.md (erstes, was Nutzer sehen)
2. Installation/Erste Schritte (Blockade für Adoption)
3. API-Referenz (Entwickler brauchen das)
4. Mitwirkungsleitfaden (für internationale Mitwirkende)

Zunächst überspringen:
- Changelogs (weniger kritisch)
- Veraltete Dokumentation
- Interne Entwicklernotizen

2. Übersetzungsstilrichtlinie beibehalten

# Übersetzungsstilrichtlinie - Spanisch

## Terminologie
- "library" → "biblioteca" (nicht "librería" was Buchhandlung bedeutet)
- "framework" → als "framework" beibehalten (weitgehend verstanden)
- "deploy" → "desplegar" (nicht "implementar")

## Ton
- Formelles "usted" für technische Dokumentation verwenden
- Umgangssprachliches "tú" für Tutorials/Anleitungen verwenden
- Knapp halten (Spanisch ist im Durchschnitt 20% länger als Englisch)

## Code
- Code-Blöcke niemals übersetzen
- Technische Begriffe auf Englisch belassen, wenn weit verbreitet

3. Übersetzungen versionieren

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

# Instalación
...

Dies hilft zu verfolgen, wann Übersetzungen hinterherhinken.

4. Community-Beiträge fördern

## Übersetzungsbeiträge

Wir freuen uns über Übersetzungen! So tragen Sie bei:

1. Dieses Repository forken
2. `docs/[language-code]/`-Verzeichnis erstellen
3. Dateien aus `docs/en/` übersetzen
4. Pull Request einreichen

Übersetzungsleitfaden: [TRANSLATION.md](./TRANSLATION.md)

Häufige Fallstricke

Fallstrick 1: URLs und Dateipfade übersetzen

❌ FALSCH:
[See installation](./instalación.md)
# Datei existiert nicht (hat Akzente)

✅ RICHTIG:
[See installation](./instalacion.md)
# Datei: instalacion.md (keine Akzente im Dateinamen)

Fallstrick 2: Relative Links kaputt machen

Englisch: docs/en/guide.md verlinkt auf: ../assets/image.png
Spanisch: docs/es/guia.md muss verlinken auf: ../assets/image.png (gleicher Pfad!)

Wenn spanischer Übersetzer schreibt: ./assets/image.png (defekt!)

Fallstrick 3: Alt-Text für Bilder vergessen

![](./screenshot.png)

Sollte sein:
![Dashboard screenshot](./screenshot.png)

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

Alt-Text ist wichtig für Barrierefreiheit!

Fallstrick 4: Inkonsistente Terminologie

Seite 1: "servidor" (Server)
Seite 3: "server" (auf Englisch belassen)
Seite 5: "servidor" wieder

Einen Begriff wählen und dabei bleiben! Glossar verwenden.

Erfolg messen

Metriken zur Verfolgung

1. Dokumentationsnutzung nach Sprache

Google Analytics (Dokumentationsseite):
- Traffic nach Sprache (es, fr, de usw.)
- Verweildauer auf Seite (höher = besseres Verständnis)
- Absprungrate (niedriger für Dokumentation in Muttersprache)

Beispiel:
Englische Dokumentation: 70% der Nutzer
Spanische Dokumentation: 15% der Nutzer (aber wachsend!)
Französische Dokumentation: 10% der Nutzer
Sonstiges: 5%

2. GitHub-Insights

GitHub Issues:
- Anzahl der in jeder Sprache erstellten Issues
- Reaktionszeit auf nicht-englische Issues

Pull Requests:
- Beiträge aus Ländern mit nicht-englischsprachigen Entwicklern
- Nach spanischen Docs: +40 % Beiträge von LATAM-Entwicklern

Stars/Forks:
- Wachstum nach Übersetzungs-Releases verfolgen

3. Community-Wachstum

Discord/Slack:
- Aktivität in sprachspezifischen Kanälen
- Fragen in Muttersprachen

Stack Overflow:
- Fragen mit Tag Ihrer Bibliothek in verschiedenen Sprachen

4. npm/PyPI-Downloads nach Geografie

npm-Download-Statistiken nach Land:
Vor chinesischer Übersetzung:
- China: 5 % der Downloads

Nach chinesischer Übersetzung:
- China: 22 % der Downloads (4,4-faches Wachstum!)

Kosten und ROI

Übersetzungsinvestition

Kleine Open-Source-Bibliothek (5.000 Wörter Dokumentation):

Professionelle Übersetzung:

Übersetzung: 5.000 × 0,08 $ = 400 $ pro Sprache
Überprüfung: 100 $
Gesamt pro Sprache: 500 $

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

KI-unterstützte Übersetzung:

KI-Übersetzung (AI Trans): 5.000 Wörter × 6 Zeichen im Durchschnitt = 30.000 Zeichen = 0,30 $
Technischer Überprüfer: 5 Stunden × 75 $ = 375 $
Gesamt pro Sprache: 375,30 $

3 Sprachen: 1.126 $ (spart 25 %)

Community-beigetragen (kostenlos, aber langsamer):

Crowdin einrichten: Kostenlos für Open Source
Übersetzungen: Kostenlos (Community-Freiwillige)
Überprüfungszeit: Ihre Zeit (5–10 Stunden pro Sprache)

3 Sprachen: 0 $ monetäre Kosten, 15–30 Stunden Zeitinvestition

ROI für Open-Source-Projekte

ROI ist nicht immer monetär – es geht um Community-Wachstum:

Metriken vor spanischen/chinesischen Übersetzungen:
- Monatliche npm-Downloads: 50.000
- GitHub-Stars: 2.500
- Mitwirkende: 40 (meist aus USA/Europa)

6 Monate nach Übersetzungen:
- Monatliche npm-Downloads: 120.000 (140 % Wachstum)
- GitHub-Stars: 6.800 (172 % Wachstum)
- Mitwirkende: 95 (55 neu aus LATAM/Asien)

Community-Wert: Unbezahlbar
Kosten: 1.500 $ für KI-unterstützt + Überprüfung

Tools und Ressourcen

Übersetzungstools

AI Trans

  • Erhält Markdown-Formatierung automatisch
  • Behält Code-Blöcke unverändert (übersetzt keinen Code)
  • Bewahrt Link-Struktur
  • 10 $ pro 1 Mio. Zeichen (Standard) oder 50 $ pro 10 Mio. Zeichen (Business)
  • Kostenloses Starter-Paket mit 100K Zeichen
  • 57 unterstützte Sprachen

DeepL API

  • Hohe Qualität für europäische Sprachen
  • Markdown-Unterstützung mit Preprocessing
  • 25 $ pro Million Zeichen + 5,49 $/Monat Abonnement

Google Cloud Translation

  • 133 Sprachen
  • Gut für breite Sprachabdeckung
  • 20 $ pro Million Zeichen
  • Kein Markdown-Bewusstsein (erfordert Preprocessing)

Markdown-Linting und -Validierung

markdownlint

  • Validiert Markdown-Syntax
  • Gewährleistet einheitliche Formatierung
  • CLI und Editor-Plugins
npm install -g markdownlint-cli
markdownlint docs/es/*.md

markdown-link-check

  • Validiert alle Links in Markdown-Dateien
  • Erkennt defekte relative Links
npm install -g markdown-link-check
markdown-link-check docs/es/README.md

Dokumentationsseiten-Builder

Docusaurus (React)

  • Beste für: React-Entwickler, moderne SPA-Docs
  • i18n integriert
  • Kostenlos

VuePress (Vue.js)

  • Beste für: Vue-Entwickler
  • Einfache Einrichtung
  • Kostenlos

MkDocs (Python)

  • Beste für: Python-Projekte
  • Minimale Konfiguration
  • Kostenlos

GitBook

  • Beste für: Nicht-Entwickler (GUI-Editor)
  • Gehostete Lösung
  • Kostenlos für Open Source

Schlussfolgerung

Die Übersetzung von Markdown-Dokumentation ist einer der einflussreichsten Beiträge, die Sie zur globalen Entwickler-Community leisten können. Indem Sie Ihr Projekt in mehreren Sprachen zugänglich machen, erschließen Sie die Adoption durch Milliarden nicht-englischsprachiger Entwickler und fördern vielfältige, internationale Zusammenarbeit.

Wichtige Erkenntnisse:

  • Code-Blöcke, Markdown-Syntax und Link-Struktur erhalten
  • Separate Verzeichnisse pro Sprache für saubere Organisation verwenden
  • Übersetzungssynchronisation mit Git-Workflows automatisieren
  • KI-Übersetzung + menschliche Überprüfung für kostengünstige Qualität nutzen
  • Mehrsprachige Seiten mit Docusaurus, VuePress oder MkDocs erstellen
  • Übersetzungen mit Metadaten und automatisierten Checks verfolgen
  • Community-Beiträge für nachhaltige Übersetzung fördern

Moderne KI-Tools wie AI Trans können Übersetzungskosten um 70–90 % senken, während alle kritischen Markdown-Elemente wie Code-Blöcke, Links und Formatierung erhalten bleiben. Der optimale Workflow: KI übersetzt die anfängliche Dokumentation (Minuten, nicht Wochen), technische Überprüfer gewährleisten Genauigkeit und Konsistenz, dann hilft die Community bei der Pflege von Updates.

Typische Kosten für Dokumentationsübersetzung:

  • Kleines Projekt (50K Zeichen): 0,50 $ mit AI Trans vs. 400 $ menschliche Übersetzung
  • Mittleres Projekt (200K Zeichen): 2 $ mit AI Trans vs. 1.600 $ menschliche Übersetzung
  • Großes Projekt (1 Mio. Zeichen): 10 $ mit AI Trans vs. 8.000 $ menschliche Übersetzung

Zeitersparnis: 95 %+ (Minuten vs. Wochen)

Egal ob Sie eine kleine Utility-Bibliothek oder ein großes Open-Source-Framework betreuen – übersetzte Dokumentation entfernt Sprachbarrieren und heißt Entwickler weltweit in Ihrem Projekt willkommen.

Bereit, Ihre Dokumentation zu übersetzen? Übersetzen Sie Ihre Markdown-Docs jetzt mit dem Code-erhaltenden Übersetzungs-Engine von AI Trans und erreichen Sie Entwickler weltweit.