Hur man översätter Markdown-dokumentation för utvecklare

Open source-projekt lever eller dör med sin dokumentation. Ett briljant bibliotek med enbart engelskspråkig README når aldrig utvecklare i Kina, Japan eller Brasilien – marknader som representerar 40 % av världens utvecklare. Ändå är översättning av markdown-dokumentation unikt utmanande: du måste bevara kodblock, behålla länkstruktur, hantera versionskontroll och hålla översättningarna synkroniserade när ditt projekt utvecklas.

Enligt GitHubs Octoverse-rapport från 2024 kommer 78 % av open source-bidrag från icke-engelsktalande, men 92 % av dokumentationen är fortfarande enbart på engelska. Detta skapar ett massivt hinder för adoption, bidrag och global gemskapsbyggande.

Denna omfattande guide visar hur du effektivt översätter markdown-dokumentation: från att bevara kodsyntax och länkar till att hantera översättningsarbetsflöden i Git, automatisera uppdateringar och bygga flerspråkiga dokumentationssajter med verktyg som Docusaurus, VuePress och MkDocs.

Varför Markdown-dokumentationsöversättning är annorlunda

Markdown är ett märkspråk designat för teknisk skrivning. När du översätter markdown-dokument översätter du inte bara prosa – du hanterar en komplex blandning av kod, formatteringssyntax, hyperlänkar, versionskontroll och kontinuerliga uppdateringar.

Utmaningen med Markdown-översättning

1. Kodblock får ALDRIG översättas

## Installation

Run the following command:

```bash
npm install awesome-library

When translating to Spanish:

• "Installation" → "Instalación" ✅
• "Run the following command:" → "Ejecuta el siguiente comando:" ✅
• npm install awesome-library → KEEP UNCHANGED ✅

Generic translators often break by translating code!

**2. Markdown-syntax måste bevaras**

```markdown
**Bold text** should stay **bold**
*Italic text* should stay *italic*
[Link text](url) should maintain link structure
`inline code` should keep backticks

Bad translation might produce:
**Negrita** (loses markdown syntax)
*Cursiva (missing closing asterisk)
[Texto](url (broken link)

3. Relativa länkar måste uppdateras för språkvarianter

English: [See API Reference](./api-reference.md)
Spanish: [Ver Referencia API](./referencia-api.md)
         ^link text translated  ^filename also translated

Both must exist and link correctly!

4. Dokumentation utvecklas – översättningarna måste det med

Day 1: Translate README.md (English → Spanish)
Day 15: English README.md updated (new feature added)
Problem: Spanish version is now outdated!

Need workflow to track and sync translation updates.

Verklig påverkan

Framgångshistoria: Vue.js

• Översatt dokumentation till 10+ språk
• Kinesisk översättning avgörande för adoption i Asien
• Community-driven översättningsarbetsflöde via GitHub
• Resultat: 40 % av npm-nedladdningar från Asien, massiv kinesisk community

Framgångshistoria: React

• Officiella översättningar till 30+ språk hanterade av community
• Separat repo för varje språk (react.dev, zh-hans.react.dev, es.react.dev)
• Översättningsguide och automationsverktyg tillhandahålls
• Resultat: Global utvecklaradoption, bidrag från 100+ länder

Framgångshistoria: Rust-programmeringsspråket

• "The Rust Book" översatt till 15+ språk
• Community underhåller översättningar via mdBook
• Japansk översättning drev 300 % ökning av japanska Rust-utvecklare
• Aktiva översättningsteam håller dokumentationen synkroniserad med engelska uppdateringar

Misslyckandefall: Övergivna översättningar Många open source-projekt har föråldrade översättningar:

• Fransk README senast uppdaterad för 2 år sedan
• Engelsk README uppdateras veckovis
• Resultat: Franska utvecklare förvirrade, överger projektet eller kämpar med föråldrad info

Markdown-grunder för översättning

Kärnelement i Markdown

Rubriker:

# Heading 1
## Heading 2
### Heading 3

Translate text, preserve symbols:
# Installation → # Instalación
## Quick Start → ## Inicio Rápido

Tryck:

**bold text** → **texto en negrita**
*italic text* → *texto en cursiva*
~~strikethrough~~ → ~~tachado~~

Keep markdown syntax exactly as-is.

Listor:

Unordered:
- Item one
- Item two
  - Nested item

Ordered:
1. First step
2. Second step
3. Third step

Translate content, keep structure:
- Primer elemento
- Segundo elemento
  - Elemento anidado

Länkar:

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

Translate text, keep URL (unless also translating linked page):
[Documentación](https://example.com/docs)

Or if Spanish docs exist:
[Documentación](https://example.com/es/docs)

Bilder:

![Alt text](image-url "Optional title")

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

Translate alt text and title:
![Captura de pantalla del panel](./images/dashboard.png "Panel de Administración")

Image filename usually stays the same (shared resource).

Kodblock:

Inline code: Use `npm install` to install packages.

Översätt prosa, bevara kod: Använd npm install för att installera paket.

Inramade kodblock:

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

ALDRIG översätt kod inuti ramar. Behåll exakt som det är.

**Tabeller:**
```markdown
| Engelska | Spanska | Franska |
|----------|---------|--------|
| Hello    | Hola    | Bonjour|
| Goodbye  | Adiós   | Au revoir|

Översätt innehållsceller, behåll strukturen:
| Engelska | Spanska | Franska |
|----------|---------|--------|
| Hello    | Hola    | Bonjour |
| Goodbye  | Adiós   | Au revoir|

Avancerade Markdown-funktioner

Blockcitat:

> Detta är viktig information som användare bör känna till.

Översätt innehåll, behåll >-symbolen:
> Detta är viktig information som användare bör känna till.

Horisontella linjer:

---
or
***
or
___

Behåll oförändrat (visuell separator, ingen text).

HTML i Markdown:

<div class="warning">
  Var försiktig när du använder den här funktionen!
</div>

Behåll HTML-taggar, översätt innehåll:
<div class="warning">
  Var försiktig när du använder den här funktionen!
</div>

Fotnoter:

Här är en fotnotsreferens[^1].

[^1]: Detta är fotnots-innehållet.

Översätt både referenskontext och fotnotstext:
Här är en fotnotsreferens[^1].

[^1]: Detta är fotnots-innehållet.

Översättningsarbetsflöde för Markdown-dokument

Alternativ 1: Separat fil per språk (Rekommenderas)

Katalogstruktur:

docs/
├── en/
│   ├── README.md
│   ├── installation.md
│   ├── api-reference.md
│   └── troubleshooting.md
├── sv/
│   ├── README.md
│   ├── installation.md
│   ├── api-referens.md
│   └── felsökning.md
├── fr/
│   ├── README.md
│   ├── installation.md
│   ├── reference-api.md
│   └── depannage.md
└── zh/
    ├── README.md
    ├── installation.md
    ├── api-reference.md
    └── troubleshooting.md

Fördelar: ✅ Ren separation (inga blandade språk) ✅ Varje språk kan ha olika filstruktur vid behov ✅ Enkelt att se vilka filer som är översatta ✅ Enkel länkning inom samma språk

Nackdelar: ❌ Svårare att spåra vilka översättningar som är föråldrade ❌ Fler filer att hantera

Alternativ 2: Suffix-baserat (Alternativ)

Katalogstruktur:

docs/
├── README.md (Engelska som standard)
├── README.sv.md (Svenska)
├── README.fr.md (Franska)
├── README.zh.md (Kinesiska)
├── installation.md
├── installation.sv.md
├── installation.fr.md
└── installation.zh.md

Fördelar: ✅ Översatta filer bredvid källan (enklare att upptäcka saknade översättningar) ✅ Alfabetiskt sorterade efter basnamn

Nackdelar: ❌ Blir rörigt med många språk ❌ Svårare att bläddra i språk-specifika dokument

Slutsats: Använd separata kataloger för projekt med omfattande dokumentation.

Steg-för-steg Översättningsprocess

Steg 1: Sätt upp översättningskatalogstruktur

# Skapa språkkataloger
mkdir -p docs/sv docs/fr docs/zh

# Kopiera engelsk struktur till nytt språk
cp -r docs/en/* docs/sv/

# Nu översätt varje fil i docs/sv/

Steg 2: Skapa översättningsspårning

translation-status.md:

# Översättningsstatus

## Svenska (sv)

| Fil | Status | Senast uppdaterad | Översättare |
|-----|--------|-------------------|-------------|
| README.md | ✅ Aktuell | 2025-01-25 | @översättare1 |
| installation.md | ⚠️ Föråldrad | 2025-01-10 | @översättare1 |
| api-reference.md | ❌ Ej påbörjad | - | - |

## Franska (fr)

| Fil | Status | Senast uppdaterad | Översättare |
|-----|--------|-------------------|-------------|
| README.md | ✅ Aktuell | 2025-01-22 | @översättare2 |
| installation.md | ✅ Aktuell | 2025-01-22 | @översättare2 |

Eller använd automatiserade verktyg (täckt senare).

Steg 3: Översätt med bevarande av kodblock

Original (en/installation.md):

# Installation

## Förutsättningar

- Node.js 18+
- npm eller yarn

## Installera via npm

Kör följande kommando i din terminal:

```bash
npm install awesome-library

Verifiera installation

Skapa en testfil test.js:

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

Kör den:

node test.js

Du bör se versionsnumret skrivas ut.

**Översatt (sv/installation.md):**
```markdown
# Installation

## Förutsättningar

- Node.js 18+
- npm eller yarn

## Installera via npm

Kör följande kommando i din terminal:

```bash
npm install awesome-library

Verifiera installationen

Skapa en testfil test.js:

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

Kör den:

node test.js

Du bör se versionsnumret skrivas ut.

**Vad som ändrades:**
- Rubriker översatta
- Prosa översatt
- Kodblock OFÖRÄNDRade (bash-kommandon, JavaScript-kod)
- Inline-kod OFÖRÄNDRAD (`test.js`, npm-paketnamn)
- Filstruktur bevarad

**Steg 4: Uppdatera interna länkar**

**Engelska (en/README.md):**
```markdown
Se [Installationsguide](./installation.md) för installationsinstruktioner.

Kolla API-referensen för detaljerad dokumentation.

Svenska (sv/README.md):

Kolla [API-referensen](./api-referens.md) för detaljerad dokumentation.

Viktigt:

• Länketext översatt
• Länk-URL uppdaterad till svenskt filnamn
• Svenska filer måste faktiskt existera!

Steg 5: Commit till Git

git add docs/sv/
git commit -m "Lägg till svensk översättning av installationsdokumentation"
git push origin main

Hantering av speciella fall

1. Kodkommentarer i kodblock

Bör du översätta kommentarer?

## Exempel

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

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

**Alternativ A: Behåll kodkommentarer på engelska**
```javascript
// Initialize the application
const app = createApp();

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

Fördelar: Universellt (utvecklare läser engelska kommentarer) Nackdelar: Mindre tillgängligt för nybörjare

Alternativ B: Översätt kodkommentarer

// Inicializar la aplicación
const app = createApp();

// Iniciar el servidor en el puerto 3000
app.listen(3000);

Fördelar: Mer tillgängligt för icke-engelska utvecklare Nackdelar: Kod kan inte kopieras direkt (blandade språk)

Rekommendation: Behåll engelska för produktionskodexempel. Översätt för tutorials/inlärningsinnehåll där förståelse > kopiera-klistra.

2. Variabel- och funktionsnamn

Aldrig översätta i kod:

// FEL - Översätt inte variabelnamn
function obtenerUsuario(idUsuario) {
  return database.buscar(idUsuario);
}

// RÄTT - Behåll kod på engelska
function getUser(userId) {
  return database.find(userId);
}

Undantag: Pseudokod eller konceptuella exempel

Engelska:

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

Svenska (accepterbart för pseudokod):

om användaren är inloggad: visa instrumentpanel annars: omdirigera till inloggning

3. Kommandorads exempel

Översätt beskrivningar, inte kommandon:

Engelska:
## 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/.

Svenska:

Skapa en ny komponent

Använd CLI:n för att skapa en komponent:

npx create-component MyComponent

Detta skapar en ny komponent i src/components/MyComponent/.

**Kommandon förblir engelska, förklaringar översätts.**

### 4. API Endpoint URLs

**Behåll URL:er oförändrade:**

```markdown
Engelska:
### Get User Profile

GET /api/v1/users/:id

Svenska:
### Hämta användarprofil

GET /api/v1/users/:id

Inte: `GET /api/v1/användare/:id` (skulle bryta API:n!)

5. Miljövariabler och konfiguration

Behåll variabelnamn, översätt beskrivningar:

Engelska:
Set your API key:

```bash
export API_KEY=your_key_here

Svenska: Ställ in din API-nyckel:

export API_KEY=din_nyckel_här

API_KEY förblir engelska (miljövariabelnamn). your_key_here → din_nyckel_här (exempelvärde, kan översättas).

### 6. Badge-länkar och sköldar

**Vanligt i README.md-filer:**

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

Svenska: Behåll badges som de är
(De är automatiska från externa tjänster, språkoberoende)

Eller om du vill ha översatt text i badges:
[![Byggstatus](https://travis-ci.org/user/repo.svg?branch=main)](https://travis-ci.org/user/repo)

Vanligtvis: Behåll engelska badges (utvecklare förväntar sig dem, status är universell).

Automatisering och verktyg

Översättningssystem för Markdown

1. Crowdin

Funktioner:

• GitHub/GitLab-integration
• Markdown-filstöd
• Bevarar kodblock automatiskt
• Community-översättning (bidragsgivare översätter via webbgränssnitt)
• Översättningsminne

Arbetsflöde:

1. Koppla Crowdin till GitHub-repo
2. Crowdin upptäcker nya/ändrade filer i docs/sv/
3. Översättare översätter via Crowdin webbgränssnitt
4. Crowdin skickar pull request med översättningar
5. Granska och slå ihop

Pris: Gratis för open-source, $40/månad+ för kommersiellt

2. Lokalise

Funktioner:

• Liknande Crowdin
• Bättre API för automatisering
• Markdown-stöd
• CLI-verktyg för synkronisering

Arbetsflöde:

# Ladda upp källfiler
lokalise2 file upload --lang-iso sv --file docs/sv/README.md

# Ladda ner översättningar
lokalise2 file download --lang-iso sv --dest docs/sv/

Pris: $120/månad+

3. Transifex

Funktioner:

• Open-source-vänligt
• Markdown-stöd
• Översättningsgranskning
• Kvalitetskontroller

Pris: Gratis för open-source, $30/månad+ för kommersiellt

Git-baserade översättningsarbetsflöden

Metod: Separa grenar för översättningar

# Huvudgren: Engelska dokument
git checkout main

# Skapa översättningsgren
git checkout -b translate/spanish

# Översätt filer
# ...

# Commit
git add docs/es/
git commit -m "Lägg till spanska översättning"

# Pusha och skapa PR
git push origin translate/spanish
# Öppna pull request på GitHub

Fördelar:

• Översättare arbetar självständigt
• Granskningsprocess via PR
• Spåra översättning som funktioner

Metod: Översättningsspårning med Git-metadata

en/installation.md:

<!--
Senast uppdaterad: 2025-01-25
Översättningsstatus:
- es: 2025-01-20 (föråldrad)
- fr: 2025-01-24 (aktuell)
- zh: ej påbörjad
-->

# Installation
...

Automatiserat skript kan kontrollera dessa kommentarer och flagga föråldrade översättningar.

Automatisk detektering av översättningsuppdateringar

Skript för att detektera föråldrade översättningar:

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} - Ej översatt")
                continue

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

            if en_modified > lang_modified:
                print(f"❌ {lang}/{file} - Föråldrad (EN uppdaterad efter översättning)")
            else:
                print(f"✅ {lang}/{file} - Aktuell")

check_translation_status()

Kör som GitHub Action:

# .github/workflows/check-translations.yml
name: Kontrollera översättningsstatus

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

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Kontrollera översättningar
        run: python scripts/check-translations.py
      - name: Kommentera på 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-assisterad Markdown-översättning

AI Trans för markdown-dokument:

Funktioner:

• Bevarar kodblock automatiskt
• Bibehåller markdown-syntax
• Behåller länkar intakta
• Snabbt (översätt hela dokumentationen på minuter)

Arbetsflöde:

# Översätt README.md från engelska till spanska
ai-translator translate \
  --input docs/en/README.md \
  --output docs/es/README.md \
  --source en \
  --target es \
  --format markdown

# Batchöversätt alla filer
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

Prissättning: $10 för 1M tecken (Standard) eller $50 för 10M tecken (Business) Gratis startpaket: 100 000 tecken att testa Typiska kostnadsexempel:

• Små dokument (50K tecken): $0.50
• Medelstora dokument (200K tecken): $2
• Stora dokument (1M tecken): $10

Bästa praxis: AI-översätt → mänsklig granskning → commit

Bygga flerspråkiga dokumentationssajter

Docusaurus (React-baserad)

Installation:

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

Katalogstruktur:

docs/
├── intro.md (Engelska som standard)
├── installation.md
i18n/
├── es/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (Spanska)
│           └── installation.md
├── fr/
│   └── docusaurus-plugin-content-docs/
│       └── current/
│           ├── intro.md (Franska)
│           └── installation.md

Bygg:

# Bygg alla språk
npm run build

# Bygg specifikt språk
npm run build -- --locale es

Resultat: Automatisk språkväxlare, SEO-optimerad flerspråkig sajt.

VuePress (Vue-baserad)

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: 'Språk',
        label: 'Engelska',
        nav: [
          { text: 'Guide', link: '/guide/' },
          { text: 'API', link: '/api/' }
        ]
      },
      '/es/': {
        selectText: 'Idiomas',
        label: 'Español',
        nav: [
          { text: 'Guía', link: '/es/guide/' },
          { text: 'API', link: '/es/api/' }
        ]
      }
    }
  }
};

**Katalogstruktur:**

docs/ ├── README.md (Engelska) ├── guide/ │ └── installation.md ├── es/ │ ├── README.md (Spanska) │ └── guide/ │ └── installation.md └── fr/ ├── README.md (Franska) └── guide/ └── installation.md

### MkDocs (Python-baserad)

**Installera med i18n-plugin:**

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

mkdocs.yml:

plugins:
  - i18n:
      default_language: en
      languages:
        en: Engelska
        es: Spanska
        fr: Franska
      material_alternate: true

nav:
  - Hem: index.md
  - Installation: installation.md
  - API-referens: api.md

Katalogstruktur:

docs/
├── index.md (Engelska som standard)
├── index.es.md (Spanska)
├── index.fr.md (Franska)
├── installation.md
├── installation.es.md
├── installation.fr.md

Bygg:

mkdocs build

Resultat: Genererar site/ med språkväxlare.

GitHub Pages Distribution

Distribuera flerspråkig Docusaurus-sajt:

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

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: Installera beroenden
        run: npm install
      - name: Bygg webbplats
        run: npm run build
      - name: Distribuera till GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Tillgång:

• Engelska: https://youruser.github.io/yourrepo/
• Spanska: https://youruser.github.io/yourrepo/es/
• Franska: https://youruser.github.io/yourrepo/fr/

Bästa praxis och fallgropar

Bästa praxis

1. Börja med sidor med hög påverkan

Prioritera:
1. README.md (första sak användare ser)
2. Installation/Kom igång (hinder för adoption)
3. API-referens (utvecklare behöver detta)
4. Bidragsguide (för internationella bidragsgivare)

Hoppa över initialt:
- Ändringsloggar (mindre kritiskt)
- Föråldrade dokument
- Interna utvecklaranteckningar

2. Upprätthåll en översättningsstilguide

# Översättningsstilguide - Spanska

## Terminologi
- "library" → "biblioteca" (inte "librería" som betyder bokhandel)
- "framework" → behåll som "framework" (allmänt förstått)
- "deploy" → "desplegar" (inte "implementar")

## Ton
- Använd formellt "usted" för tekniska dokument
- Använd informellt "tú" för handledningar/guider
- Var koncist (Spanska är 20% längre än Engelska i genomsnitt)

## Kod
- Översätt aldrig kodblock
- Behåll tekniska termer på Engelska om de används allmänt

3. Versionshantera dina översättningar

README.md:
<!--
Translation: Spanska
Source version: v2.5.0
Översatt: 2025-01-25
Översättare: @username
-->

# Installation
...

Detta hjälper till att spåra när översättningar halkar efter.

4. Uppmuntra community-bidrag

## Bidra med översättningar

Vi välkomnar översättningar! För att bidra:

1. Forka detta repository
2. Skapa `docs/[språkkod]/` katalog
3. Översätt filer från `docs/en/`
4. Skicka en pull request

Översättningsguide: [TRANSLATION.md](./TRANSLATION.md)

Vanliga fallgropar

Fallgrop 1: Översätta URL:er och filvägar

❌ FEL:
[Se installation](./instalación.md)
# Filen existerar inte (har accenterade tecken)

✅ RÄTT:
[Se installation](./instalacion.md)
# Fil: instalacion.md (inga accenter i filnamn)

Fallgrop 2: Bryta relativa länkar

Engelska: docs/en/guide.md länkar till: ../assets/image.png
Spanska: docs/es/guia.md måste länka till: ../assets/image.png (samma sökväg!)

Om spansk översättare skriver: ./assets/image.png (trasigt!)

Fallgrop 3: Glömma bild alt-text

![](./screenshot.png)

Borde vara:
![Dashboard-skärmdump](./screenshot.png)

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

Alt-text är viktigt för tillgänglighet!

Fallgrop 4: Inkonsekvent terminologi

Sida 1: "servidor" (server)
Sida 3: "server" (behållen på engelska)
Sida 5: "servidor" igen

Välj en och håll dig till den! Använd ordlista.

Mäta framgång

Metriker att spåra

1. Dokumentationsanvändning per språk

Google Analytics (dokumentationssajt):
- Trafik per språk (es, fr, de, osv.)
- Tid på sida (högre = bättre förståelse)
- Avvisningsfrekvens (lägre för dokument på modersmålet)

Exempel:
Engelska dokument: 70% av användare
Spanska dokument: 15% av användare (men växer!)
Franska dokument: 10% av användare
Övrigt: 5%

2. GitHub-insikter

GitHub Issues:
- Antal rapporterade issues på varje språk
- Svarstid på icke-engelska issues

Pull Requests:
- Bidrag från länder med icke-engelska språk
- Efter spanska dokumentation: +40% bidrag från LATAM-utvecklare

Stars/Forks:
- Följ tillväxt efter översättningsreleaser

3. Communitytillväxt

Discord/Slack:
- Aktivitet i språkspecifika kanaler
- Frågor på modersmål

Stack Overflow:
- Frågor taggade med ditt bibliotek på olika språk

4. npm/PyPI-nedladdningar per geografi

npm-nedladdningsstatistik per land:
Före kinesisk översättning:
- Kina: 5% av nedladdningar

Efter kinesisk översättning:
- Kina: 22% av nedladdningar (4,4x tillväxt!)

Kostnader och ROI

Översättningsinvestering

Liten open-source-bibliotek (5 000 ord dokumentation):

Professionell översättning:

Översättning: 5 000 × $0,08 = $400 per språk
Granskning: $100
Totalt per språk: $500

3 språk (es, fr, zh): $1 500

AI-assisterad översättning:

AI-översättning (AI Trans): 5 000 ord × 6 tecken i snitt = 30 000 tecken = $0,30
Teknisk granskare: 5 timmar × $75 = $375
Totalt per språk: $375,30

3 språk: $1 126 (sparar 25%)

Community-bidrag (gratis men långsammare):

Upprätta Crowdin: Gratis för open-source
Översättningar: Gratis (community-volontärer)
Granskningstid: Din tid (5-10 timmar per språk)

3 språk: $0 monetär kostnad, 15-30 timmars tidsinvestering

ROI för Open-Source-projekt

ROI är inte alltid monetärt – det är communitytillväxt:

Mätvärden före spanska/kinesiska översättningar:
- Månatliga npm-nedladdningar: 50 000
- GitHub-stjärnor: 2 500
- Bidragsgivare: 40 (mest USA/Europa)

6 månader efter översättningar:
- Månatliga npm-nedladdningar: 120 000 (140% tillväxt)
- GitHub-stjärnor: 6 800 (172% tillväxt)
- Bidragsgivare: 95 (55 nya från LATAM/Asien)

Communityvärde: Ovärderligt
Kostnad: $1 500 för AI-assisterad + granskning

Verktyg och resurser

Översättningsverktyg

AI Trans

• Bevarar markdown-formatering automatiskt
• Behåller kodblock intakta (översätter aldrig kod)
• Bibehåller länkstruktur
• $10 per 1M tecken (Standard) eller $50 per 10M tecken (Business)
• Gratis 100K tecken startpaket
• 57 språk stöds

DeepL API

• Högkvalitativa europeiska språk
• Markdown-stöd med förbehandling
• $25 per miljon tecken + $5,49/månad prenumeration

Google Cloud Translation

• 133 språk
• Bra för bred språktäckning
• $20 per miljon tecken
• Ingen markdown-medvetenhet (kräver förbehandling)

Markdown-lintning och validering

markdownlint

• Validerar markdown-syntax
• Säkerställer konsekvent formatering
• CLI och editor-plugins

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

markdown-link-check

• Validerar alla länkar i markdown-filer
• Fångar trasiga relativa länkar

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

Dokumentationssajtsbyggare

Docusaurus (React)

• Bäst för: React-utvecklare, moderna SPA-dokumentationer
• i18n inbyggt
• Gratis

VuePress (Vue.js)

• Bäst för: Vue-utvecklare
• Enkel uppsättning
• Gratis

MkDocs (Python)

• Bäst för: Python-projekt
• Minimal konfiguration
• Gratis

GitBook

• Bäst för: Icke-utvecklare (GUI-editor)
• Värd lösning
• Gratis för open-source

Slutsats

Att översätta markdown-dokumentation är ett av de mest effektiva bidragen du kan göra till att bygga en global utvecklarsamfund. Genom att göra ditt projekt tillgängligt på flera språk låser du upp adoption från miljarder icke-engelska talande utvecklare och främjar mångsidigt, internationellt samarbete.

Viktiga slutsatser:

• Bevara kodblock, markdown-syntax och länkstruktur
• Använd separata kataloger per språk för ren organisation
• Automatisera översättningssynkronisering med Git-arbetsflöden
• Använd AI-översättning + mänsklig granskning för kostnadseffektiv kvalitet
• Bygg flerspråkiga sajter med Docusaurus, VuePress eller MkDocs
• Spåra översättningar med metadata och automatiserade kontroller
• Uppmuntra community-bidrag för hållbar översättning

Moderna AI-verktyg som AI Trans kan minska översättningskostnader med 70-90% samtidigt som alla kritiska markdown-element som kodblock, länkar och formatering bevaras. Det optimala arbetsflödet: AI översätter initial dokumentation (minuter, inte veckor), tekniska granskare säkerställer noggrannhet och konsistens, sedan hjälper communityn till att underhålla uppdateringar.

Typisk dokumentationsöversättningskostnad:

• Litet projekt (50K tecken): $0,50 med AI Trans vs. $400 mänsklig översättning
• Medelstort projekt (200K tecken): $2 med AI Trans vs. $1 600 mänsklig översättning
• Stort projekt (1M tecken): $10 med AI Trans vs. $8 000 mänsklig översättning

Tidsbesparing: 95%+ (minuter vs. veckor)

Oavsett om du underhåller en liten utility-bibliotek eller ett stort open-source-ramverk, tar översatt dokumentation bort språkbarriärer och välkomnar utvecklare världen över till ditt projekt.

Redo att översätta din dokumentation? Börja översätta dina markdown-dokument med AI Trans kodbevarande översättningsmotor och nå globala utvecklare.