Come tradurre la documentazione Markdown per sviluppatori
I progetti open-source vivono o muoiono grazie alla loro documentazione. Una libreria brillante con README solo in inglese non raggiungerà mai gli sviluppatori in Cina, Giappone o Brasile—mercati che rappresentano il 40% della popolazione mondiale di sviluppatori. Eppure, la traduzione della documentazione markdown è unica nel suo genere e particolarmente challenging: è necessario preservare i blocchi di codice, mantenere la struttura dei link, gestire il controllo di versione e tenere le traduzioni sincronizzate mentre il progetto evolve.
Secondo il report GitHub's 2024 Octoverse, il 78% dei contributi open-source proviene da parlanti non madrelingua inglese, eppure il 92% della documentazione rimane solo in inglese. Questo crea una barriera massiccia all'adozione, al contributo e alla costruzione di comunità globali.
Questa guida completa ti mostrerà come tradurre efficacemente la documentazione markdown: dalla preservazione della sintassi del codice e dei link alla gestione dei workflow di traduzione in Git, all'automazione degli aggiornamenti e alla creazione di siti di documentazione multilingue con tool come Docusaurus, VuePress e MkDocs.
Perché la Traduzione della Documentazione Markdown è Diversa
Markdown è un linguaggio di markup progettato per la scrittura tecnica. Quando traduci docs markdown, non stai solo traducendo il testo in prosa—stai gestendo una miscela complessa di codice, sintassi di formattazione, iperlink, controllo di versione e aggiornamenti continui.
La Sfida della Traduzione Markdown
1. I Blocchi di Codice Non Devono Mai Essere Tradotti
## Installation
Run the following command:
```bash
npm install awesome-library
Quando traduci in spagnolo:
- "Installation" → "Instalación" ✅
- "Run the following command:" → "Ejecuta el siguiente comando:" ✅
- `npm install awesome-library` → MANTIENI INVARIATO ✅
I traduttori generici spesso rovinano tutto traducendo il codice!
2. La Sintassi Markdown Deve Essere Preservata
**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. I Link Relativi Devono Aggiornarsi per le Versioni Linguistiche
English: [See API Reference](./api-reference.md)
Spanish: [Ver Referencia API](./referencia-api.md)
^testo link tradotto ^nome file anche tradotto
Entrambi devono esistere e linkare correttamente!
4. La Documentazione Evolves—Anche le Traduzioni Devono
Giorno 1: Traduci README.md (English → Spanish)
Giorno 15: README.md inglese aggiornato (nuova feature aggiunta)
Problema: La versione spagnola è ora obsoleta!
Serve un workflow per tracciare e sincronizzare gli aggiornamenti delle traduzioni.
Impatto nel Mondo Reale
Storia di Successo: Vue.js
- Documentazione tradotta in oltre 10 lingue
- Traduzione cinese cruciale per l'adozione in Asia
- Workflow di traduzione community-driven via GitHub
- Risultato: 40% dei download npm dall'Asia, community cinese massiccia
Storia di Successo: React
- Traduzioni ufficiali in oltre 30 lingue gestite dalla community
- Repo separati per ogni lingua (react.dev, zh-hans.react.dev, es.react.dev)
- Guida alla traduzione e tool di automazione forniti
- Risultato: Adozione globale da sviluppatori, contributi da oltre 100 paesi
Storia di Successo: Linguaggio di Programmazione Rust
- "The Rust Book" tradotto in oltre 15 lingue
- Community mantiene traduzioni via mdBook
- Traduzione giapponese ha portato a un aumento del 300% degli sviluppatori Rust giapponesi
- Team di traduzione attivi mantengono i docs sincronizzati con gli aggiornamenti inglesi
Caso di Fallimento: Traduzioni Abbandonate Molti progetti open-source hanno traduzioni obsolete:
- README francese aggiornato l'ultima volta 2 anni fa
- README inglese aggiornato settimanalmente
- Risultato: Sviluppatori francesi confusi, abbandonano il progetto o lottano con info obsolete
Fondamenti Markdown per la Traduzione
Elementi Core di Markdown
Intestazioni:
# Heading 1
## Heading 2
### Heading 3
Traduci il testo, preserva i simboli:
# Installation → # Instalación
## Quick Start → ## Inicio Rápido
Enfasi:
**bold text** → **testo in grassetto**
*italic text* → *testo in corsivo*
~~strikethrough~~ → ~~barrato~~
Mantieni la sintassi markdown esattamente com'è.
Elenchi:
Non ordinati:
- Item one
- Item two
- Nested item
Ordinati:
1. First step
2. Second step
3. Third step
Traduci il contenuto, mantieni la struttura:
- Primo elemento
- Secondo elemento
- Elemento annidato
Link:
[Link text](url)
[Documentation](https://example.com/docs)
Traduci il testo, mantieni l'URL (a meno che non traduci anche la pagina linkata):
[Documentazione](https://example.com/docs)
O se esistono docs spagnoli:
[Documentazione](https://example.com/es/docs)
Immagini:
Traduci alt text e titolo:
Il nome del file immagine di solito rimane lo stesso (risorsa condivisa).
Blocchi di codice:
Codice inline: Usa `npm install` per installare pacchetti.
Traduci il testo in prosa, preserva il codice: Usa npm install per installare pacchetti.
Blocchi di codice delimitati:
function greet(name) {
console.log(`Hello, ${name}!`);
}
NON tradurre mai il codice all'interno dei delimitatori. Mantienilo esattamente com'è.
**Tabelle:**
```markdown
| Inglese | Spagnolo | Francese |
|---------|----------|----------|
| Hello | Hola | Bonjour |
| Goodbye | Adiós | Au revoir|
Traduci le celle di contenuto, mantieni la struttura:
| Inglese | Spagnolo | Francese |
|---------|----------|----------|
| Hello | Hola | Bonjour |
| Goodbye | Adiós | Au revoir|
Funzionalità Avanzate di Markdown
Citazioni a blocco:
> Questa è un'informazione importante che gli utenti dovrebbero sapere.
Traduci il contenuto, mantieni il simbolo > :
> Questa è un'informazione importante che gli utenti dovrebbero sapere.
Righe orizzontali:
---
o
***
o
___
Mantienile invariate (separatore visivo, nessun testo).
HTML in Markdown:
<div class="warning">
Fai attenzione quando usi questa funzionalità!
</div>
Mantieni i tag HTML, traduci il contenuto:
<div class="warning">
Fai attenzione quando usi questa funzionalità!
</div>
Note a piè di pagina:
Ecco un riferimento a una nota a piè di pagina[^1].
[^1]: Questo è il contenuto della nota a piè di pagina.
Traduci sia il contesto del riferimento che il testo della nota:
Qui c'è un riferimento a nota a piè di pagina[^1].
[^1]: Questo è il contenuto della nota a piè di pagina.
Flusso di Lavoro per la Traduzione di Documenti Markdown
Opzione 1: File Separati per Lingua (Raccomandata)
Struttura delle directory:
docs/
├── it/
│ ├── README.md
│ ├── installazione.md
│ ├── riferimento-api.md
│ └── risoluzione-problemi.md
├── 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
Pro: ✅ Separazione pulita (nessuna lingua mista) ✅ Ogni lingua può avere una struttura di file diversa se necessario ✅ Facile vedere quali file sono tradotti ✅ Collegamenti semplici all'interno della stessa lingua
Contro: ❌ Più difficile tracciare quali traduzioni sono obsolete ❌ Più file da gestire
Opzione 2: Basata su Suffisso (Alternativa)
Struttura delle directory:
docs/
├── README.md (Inglese predefinito)
├── README.it.md (Italiano)
├── README.es.md (Spagnolo)
├── README.fr.md (Francese)
├── README.zh.md (Cinese)
├── installation.md
├── installation.it.md
├── installation.es.md
├── installation.fr.md
└── installation.zh.md
Pro: ✅ File tradotti accanto alla sorgente (più facile individuare traduzioni mancanti) ✅ Ordinati alfabeticamente per nome base
Contro: ❌ Diventa disordinato con molte lingue ❌ Più difficile navigare la documentazione specifica per lingua
Verdetto: Usa directory separate per progetti con documentazione completa.
Processo di Traduzione Passo per Passo
Passo 1: Imposta la Struttura delle Directory per la Traduzione
# Crea directory per le lingue
mkdir -p docs/it docs/fr docs/zh
# Copia la struttura inglese nella nuova lingua
cp -r docs/en/* docs/it/
# Ora traduci ogni file in docs/it/
Passo 2: Crea il Tracciamento delle Traduzioni
translation-status.md:
# Stato delle Traduzioni
## Italiano (it)
| File | Stato | Ultimo Aggiornamento | Traduttore |
|------|-------|---------------------|------------|
| README.md | ✅ Aggiornato | 2025-01-25 | @translator1 |
| installation.md | ⚠️ Obsoleto | 2025-01-10 | @translator1 |
| api-reference.md | ❌ Non iniziato | - | - |
## Francese (fr)
| File | Stato | Ultimo Aggiornamento | Traduttore |
|------|-------|---------------------|------------|
| README.md | ✅ Aggiornato | 2025-01-22 | @translator2 |
| installation.md | ✅ Aggiornato | 2025-01-22 | @translator2 |
O usa strumenti automatizzati (coperti più avanti).
Passo 3: Traduci mantenendo i Blocchi di Codice Intatti
Originale (en/installation.md):
# Installation
## Prerequisites
- Node.js 18+
- npm or yarn
## Install via npm
Run the following command in your terminal:
```bash
npm install awesome-library
Verify Installation
Create a test file test.js:
const awesome = require('awesome-library');
console.log(awesome.version);
Run it:
node test.js
You should see the version number printed.
**Tradotto (it/installazione.md):**
```markdown
# Installazione
## Prerequisiti
- Node.js 18+
- npm o yarn
## Installa tramite npm
Esegui il seguente comando nel tuo terminale:
```bash
npm install awesome-library
Verifica l'Installazione
Crea un file di test test.js:
const awesome = require('awesome-library');
console.log(awesome.version);
Eseguilo:
node test.js
Dovresti vedere il numero di versione stampato.
**Cosa è cambiato:**
- Intestazioni tradotte
- Prosa tradotta
- Blocchi di codice INVARIATI (comandi bash, codice JavaScript)
- Codice inline INVARIATO (`test.js`, nomi pacchetti npm)
- Struttura file mantenuta
**Passo 4: Aggiorna i Collegamenti Interni**
**Inglese (en/README.md):**
```markdown
See [Installation Guide](./installation.md) for setup instructions.
Controlla la Riferimento API per la documentazione dettagliata.
Italiano (it/README.md):
Consulta la [Guía de Instalación](./instalacion.md) per le istruzioni di configurazione.
Controlla la [Riferimento API](./riferimento-api.md) per la documentazione dettagliata.
Critico:
- Testo del link tradotto
- URL del link aggiornato al nome file italiano
- I file italiani devono esistere realmente!
Passo 5: Commit su Git
git add docs/it/
git commit -m "Aggiungi traduzione italiana della documentazione di installazione"
git push origin main
Gestione dei Casi Speciali
1. Commenti nel Codice nei Blocchi di Codice
Dovresti tradurre i commenti?
## Esempio
```javascript
// Initialize the application
const app = createApp();
// Start the server on port 3000
app.listen(3000);
**Opzione A: Mantieni i commenti del codice in inglese**
```javascript
// Initialize the application
const app = createApp();
// Start the server on port 3000
app.listen(3000);
Pro: Universale (gli sviluppatori leggono commenti in inglese) Contro: Meno accessibile per i principianti
Opzione B: Traduci i commenti del codice
// Inizializza l'applicazione
const app = createApp();
// Avvia il server sulla porta 3000
app.listen(3000);
Pro: Più accessibile per sviluppatori non anglofoni Contro: Il codice non è più copiabile/incollabile (mix di lingue)
Raccomandazione: Mantieni l'inglese per esempi di codice di produzione. Traduci per contenuti tutorial/apprendimento dove la comprensione > copia-incolla.
2. Nomi di Variabili e Funzioni
Non tradurre mai nel codice:
// SBAGLIATO - Non tradurre i nomi delle variabili
function ottenereUsuario(idUsuario) {
return database.buscar(idUsuario);
}
// GIUSTO - Mantieni il codice in inglese
function getUser(userId) {
return database.find(userId);
}
Eccezione: Pseudocodice o esempi concettuali
Inglese:
if user is logged in: show dashboard else: redirect to login
Italiano (accettabile per pseudocodice):
se utente è loggato: mostra dashboard altrimenti: reindirizza al login
3. Esempi di Command Line
Traduci le descrizioni, non i comandi:
Inglese:
## 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/.
Italiano:
Genera un Nuovo Componente
Usa la CLI per creare un componente:
npx create-component MyComponent
Questo crea un nuovo componente in src/components/MyComponent/.
**I comandi rimangono in inglese, le spiegazioni si traducono.**
### 4. URL degli Endpoint API
**Mantieni gli URL invariati:**
```markdown
Inglese:
### Get User Profile
GET /api/v1/users/:id
Italiano:
### Ottieni Profilo Utente
GET /api/v1/users/:id
Non: `GET /api/v1/users/:id` (romperebbe l'API!)
5. Variabili d'Ambiente e Configurazione
Mantieni i nomi delle variabili, traduci le descrizioni:
Inglese:
Set your API key:
```bash
export API_KEY=your_key_here
Italiano: Configura la tua chiave API:
export API_KEY=la_tua_chiave_qua
API_KEY rimane in inglese (nome variabile d'ambiente).
your_key_here → la_tua_chiave_qua (valore di esempio, può essere tradotto).
### 6. Badge e Link Shield
**Comuni nei file README.md:**
```markdown
Inglese:
[](https://travis-ci.org/user/repo)
[](https://www.npmjs.com/package/awesome-lib)
Italiano: Mantieni i badge così come sono
(Sono automatici da servizi esterni, indipendenti dalla lingua)
O se vuoi badge con testo tradotto:
[](https://travis-ci.org/user/repo)
Di solito: Mantieni i badge in inglese (gli sviluppatori se li aspettano, lo stato è universale).
Automazione e Strumenti
Sistemi di Gestione Traduzione per Markdown
1. Crowdin
Funzionalità:
- Integrazione GitHub/GitLab
- Supporto file Markdown
- Preserva automaticamente i blocchi di codice
- Traduzione comunitaria (i contributori traducono via interfaccia web)
- Memoria di traduzione
Flusso di lavoro:
1. Collega Crowdin al repo GitHub
2. Crowdin rileva nuovi/file modificati in docs/it/
3. I traduttori traducono via interfaccia web Crowdin
4. Crowdin invia pull request con traduzioni
5. Rivedi e mergia
Prezzi: Gratuito per open-source, $40/mese+ per commerciale
2. Lokalise
Funzionalità:
- Simile a Crowdin
- Migliore API per automazione
- Supporto Markdown
- Strumento CLI per sincronizzazione
Flusso di lavoro:
# Carica file sorgente
lokalise2 file upload --lang-iso it --file docs/it/README.md
# Scarica traduzioni
lokalise2 file download --lang-iso it --dest docs/it/
Prezzi: $120/mese+
3. Transifex
Funzionalità:
- Amichevole per open-source
- Supporto Markdown
- Revisioni traduzioni
- Controlli qualità
Prezzi: Gratuito per open-source, $30/mese+ per commerciale
Flussi di Lavoro Traduzione Basati su Git
Approccio: Branch separati per le traduzioni
# Branch principale: documentazione in inglese
git checkout main
# Crea branch per la traduzione
git checkout -b translate/spanish
# Traduci i file
# ...
# Commit
git add docs/es/
git commit -m "Aggiungi traduzione spagnola"
# Push e crea PR
git push origin translate/spanish
# Apri pull request su GitHub
Vantaggi:
- I traduttori lavorano in modo indipendente
- Processo di revisione tramite PR
- Tracciamento delle traduzioni come feature
Approccio: Tracciamento traduzioni con metadati Git
en/installation.md:
<!--
Ultimo aggiornamento: 2025-01-25
Stato traduzione:
- es: 2025-01-20 (superata)
- fr: 2025-01-24 (aggiornata)
- zh: non iniziata
-->
# Installazione
...
Uno script automatico può controllare questi commenti e segnalare le traduzioni superate.
Rilevamento automatico aggiornamenti traduzioni
Script per rilevare traduzioni superate:
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} - Non tradotto")
continue
en_modified = os.path.getmtime(en_file)
lang_modified = os.path.getmtime(lang_file)
if en_modified > lang_modified:
print(f"❌ {lang}/{file} - Superata (EN aggiornata dopo traduzione)")
else:
print(f"✅ {lang}/{file} - Aggiornata")
check_translation_status()
Esegui come GitHub Action:
# .github/workflows/check-translations.yml
name: Controlla stato traduzioni
on:
push:
paths:
- 'docs/**'
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Controlla traduzioni
run: python scripts/check-translations.py
- name: Commenta 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
Traduzione Markdown assistita da AI
AI Trans per documentazione markdown:
Caratteristiche:
- Preserva automaticamente i blocchi di codice
- Mantiene la sintassi markdown
- Conserva i link intatti
- Veloce (traduce intera documentazione in minuti)
Flusso di lavoro:
# Traduci README.md dall'inglese allo spagnolo
ai-translator translate \
--input docs/en/README.md \
--output docs/es/README.md \
--source en \
--target es \
--format markdown
# Traduci in batch tutti i file
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
Prezzi: $10 per 1M caratteri (Standard) o $50 per 10M caratteri (Business) Pacchetto Starter Gratuito: 100.000 caratteri per test Esempi di costi tipici:
- Documentazione piccola (50K chars): $0.50
- Documentazione media (200K chars): $2
- Documentazione grande (1M chars): $10
Migliore pratica: Traduci con AI → revisione umana → commit
Creazione siti di documentazione multilingue
Docusaurus (basato su React)
Configurazione:
npx create-docusaurus@latest my-docs classic
cd my-docs
Configurazione i18n (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: '中文' }
}
},
// ...
};
Struttura directory:
docs/
├── intro.md (inglese predefinito)
├── installation.md
i18n/
├── es/
│ └── docusaurus-plugin-content-docs/
│ └── current/
│ ├── intro.md (spagnolo)
│ └── installation.md
├── fr/
│ └── docusaurus-plugin-content-docs/
│ └── current/
│ ├── intro.md (francese)
│ └── installation.md
Build:
# Build tutte le lingue
npm run build
# Build lingua specifica
npm run build -- --locale es
Risultato: Selettore lingua automatico, sito multilingue ottimizzato per SEO.
VuePress (basato su Vue)
Configurazione i18n (.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: 'Documentazione per awesome library'
}
}, themeConfig: { locales: { '/': { selectText: 'Languages', label: 'English', 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/' } ] } } } };
Directory:
docs/
├── README.md (English)
├── guide/
│ └── installation.md
├── es/
│ ├── README.md (Spanish)
│ └── guide/
│ └── installation.md
└── fr/
├── README.md (French)
└── guide/
└── installation.md
MkDocs (Python-based)
Install with i18n plugin:
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 (English default)
├── index.es.md (Spanish)
├── index.fr.md (French)
├── installation.md
├── installation.es.md
├── installation.fr.md
Build:
mkdocs build
Result: Generates site/ with language switcher.
GitHub Pages Deployment
Deploy multilingual Docusaurus site:
# .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
Access:
- English: https://youruser.github.io/yourrepo/
- Spanish: https://youruser.github.io/yourrepo/es/
- French: https://youruser.github.io/yourrepo/fr/
Best Practices and Pitfalls
Best Practices
1. Start with high-impact pages
Prioritize:
1. README.md (first thing users see)
2. Installation/Getting Started (blocker for adoption)
3. API Reference (developers need this)
4. Contributing Guide (for international contributors)
Skip initially:
- Changelogs (less critical)
- Deprecated docs
- Internal developer notes
2. Maintain a translation style guide
# Translation Style Guide - Spanish
## Terminology
- "library" → "biblioteca" (not "librería" which means bookstore)
- "framework" → keep as "framework" (widely understood)
- "deploy" → "desplegar" (not "implementar")
## Tone
- Use formal "usted" for technical docs
- Use informal "tú" for tutorials/guides
- Be concise (Spanish is 20% longer than English on average)
## Code
- Never translate code blocks
- Keep technical terms in English if widely used
3. Version your translations
README.md:
<!--
Translation: Spanish
Source version: v2.5.0
Translated: 2025-01-25
Translator: @username
-->
# Instalación
...
This helps track when translations fall behind.
4. Encourage community contributions
## Contributing Translations
We welcome translations! To contribute:
1. Fork this repository
2. Create `docs/[language-code]/` directory
3. Translate files from `docs/en/`
4. Submit a pull request
Translation guide: [TRANSLATION.md](./TRANSLATION.md)
Common Pitfalls
Pitfall 1: Translating URLs and file paths
❌ WRONG:
[See installation](./instalación.md)
# File doesn't exist (has accented characters)
✅ RIGHT:
[See installation](./instalacion.md)
# File: instalacion.md (no accents in filename)
Pitfall 2: Breaking relative links
English: docs/en/guide.md links to: ../assets/image.png
Spanish: docs/es/guia.md must link to: ../assets/image.png (same path!)
If Spanish translator writes: ./assets/image.png (broken!)
Pitfall 3: Forgetting image alt text
Should be:
Spanish:
Alt text is important for accessibility!
Pitfall 4: Inconsistent terminology
Page 1: "servidor" (server)
Page 3: "server" (kept in English)
Page 5: "servidor" again
Pick one and stick with it! Use glossary.
Measuring Success
Metrics to Track
1. Documentation usage by language
Google Analytics (documentation site):
- Traffic by language (es, fr, de, etc.)
- Time on page (higher = better understanding)
- Bounce rate (lower for native language docs)
Example:
English docs: 70% of users
Spanish docs: 15% of users (but growing!)
French docs: 10% of users
Other: 5%
2. Insight GitHub
GitHub Issues:
- Conta le issue aperte in ogni lingua
- Tempo di risposta alle issue non in inglese
Pull Requests:
- Contributi da paesi non anglofoni
- Dopo la documentazione in spagnolo: +40% contributi da sviluppatori LATAM
Stars/Forks:
- Monitora la crescita dopo i rilasci delle traduzioni
3. Crescita della community
Discord/Slack:
- Attività dei canali specifici per lingua
- Domande in lingue native
Stack Overflow:
- Domande taggate con la tua libreria in diverse lingue
4. Download npm/PyPI per geografia
npm download stats per paese:
Prima della traduzione in cinese:
- Cina: 5% dei download
Dopo la traduzione in cinese:
- Cina: 22% dei download (crescita 4,4x!)
Costi e ROI
Investimento in traduzione
Piccola libreria open-source (5.000 parole di documentazione):
Traduzione professionale:
Traduzione: 5.000 × 0,08$ = 400$ per lingua
Revisione: 100$
Totale per lingua: 500$
3 lingue (es, fr, zh): 1.500$
Traduzione assistita da AI:
Traduzione AI (AI Trans): 5.000 parole × 6 caratteri medi = 30.000 caratteri = 0,30$
Revisore tecnico: 5 ore × 75$ = 375$
Totale per lingua: 375,30$
3 lingue: 1.126$ (risparmio 25%)
Contributi della community (gratuiti ma più lenti):`
Configura Crowdin: Gratuito per open-source
Traduzioni: Gratuite (volontari della community)
Tempo di revisione: Il tuo tempo (5-10 ore per lingua)
3 lingue: 0$ di costo monetario, 15-30 ore di investimento temporale
ROI per progetti open-source
L'ROI non è sempre monetario: è la crescita della community:
Metriche prima delle traduzioni in spagnolo/cinese:
- Download npm mensili: 50.000
- Stelle GitHub: 2.500
- Contributori: 40 (per lo più USA/Europa)
6 mesi dopo le traduzioni:
- Download npm mensili: 120.000 (crescita 140%)
- Stelle GitHub: 6.800 (crescita 172%)
- Contributori: 95 (55 nuovi da LATAM/Asia)
Valore della community: Inestimabile
Costo: 1.500$ per traduzione assistita da AI + revisione
Strumenti e risorse
Strumenti di traduzione
AI Trans
- Preserva automaticamente la formattazione markdown
- Mantiene intatti i blocchi di codice (non traduce mai il codice)
- Conserva la struttura dei link
- 10$ per 1M di caratteri (Standard) o 50$ per 10M di caratteri (Business)
- Pacchetto starter gratuito da 100K caratteri
- 57 lingue supportate
DeepL API
- Alta qualità per lingue europee
- Supporto markdown con pre-elaborazione
- 25$ per milione di caratteri + abbonamento 5,49$/mese
Google Cloud Translation
- 133 lingue
- Buono per ampia copertura linguistica
- 20$ per milione di caratteri
- Nessuna consapevolezza markdown (richiede pre-elaborazione)
Linting e validazione Markdown
markdownlint
- Valida la sintassi markdown
- Garantisce formattazione consistente
- CLI e plugin per editor
npm install -g markdownlint-cli
markdownlint docs/es/*.md
markdown-link-check
- Valida tutti i link nei file markdown
- Rileva link relativi rotti
npm install -g markdown-link-check
markdown-link-check docs/es/README.md
Generatori di siti di documentazione
Docusaurus (React)
- Ideale per: Sviluppatori React, docs SPA moderne
- i18n integrato
- Gratuito
VuePress (Vue.js)
- Ideale per: Sviluppatori Vue
- Setup semplice
- Gratuito
MkDocs (Python)
- Ideale per: Progetti Python
- Configurazione minima
- Gratuito
GitBook
- Ideale per: Non sviluppatori (editor GUI)
- Soluzione hosted
- Gratuito per open-source
Conclusione
Tradurre la documentazione markdown è uno dei contributi ad alto impatto che puoi fare per la costruzione di una community globale di sviluppatori. Rendendo il tuo progetto accessibile in più lingue, sblocchi l'adozione da miliardi di sviluppatori non anglofoni e promuovi una collaborazione diversificata e internazionale.
Punti chiave:
- Preserva blocchi di codice, sintassi markdown e struttura dei link
- Usa directory separate per lingua per un'organizzazione pulita
- Automatizza la sincronizzazione delle traduzioni con i workflow Git
- Sfrutta traduzione AI + revisione umana per qualità conveniente
- Costruisci siti multilingue con Docusaurus, VuePress o MkDocs
- Traccia le traduzioni con metadati e controlli automatizzati
- Incoraggia contributi della community per traduzioni sostenibili
Strumenti AI moderni come AI Trans possono ridurre i costi di traduzione del 70-90% preservando tutti gli elementi markdown critici come blocchi di codice, link e formattazione. Il workflow ottimale: AI traduce la documentazione iniziale (minuti, non settimane), revisori tecnici assicurano accuratezza e coerenza, poi la community aiuta a mantenere gli aggiornamenti.
Costo tipico di traduzione documentazione:
- Piccolo progetto (50K caratteri): 0,50$ con AI Trans vs. 400$ traduzione umana
- Progetto medio (200K caratteri): 2$ con AI Trans vs. 1.600$ traduzione umana
- Grande progetto (1M caratteri): 10$ con AI Trans vs. 8.000$ traduzione umana
Risparmio tempo: 95%+ (minuti vs. settimane)
Che tu stia mantenendo una piccola libreria di utilità o un importante framework open-source, la documentazione tradotta rimuove le barriere linguistiche e accoglie sviluppatori di tutto il mondo nel tuo progetto.
Pronto a tradurre la tua documentazione? Inizia a tradurre i tuoi documenti markdown con il motore di traduzione code-preserving di AI Trans e raggiungi sviluppatori globali.