Internazionalizzazione (i18n)
On this page
Internazionalizzazione (i18n)
Traduci la tua documentazione in altre lingue, ognuna con il proprio
prefisso URL, il proprio <html lang dir>, e un selettore di lingua
automatico - nessun plugin, nessun passaggio di build separato.
Aggiungere una locale
Il contenuto tradotto vive in docs/i18n/<code>/, rispecchiando il tuo
albero docs/ regolare pagina per pagina:
docs/
├── index.md
├── guides/
│ └── setup.md
└── i18n/
├── es/
│ ├── index.md
│ └── guides/
│ └── setup.md
└── ar/
└── index.md
<code> diventa sia il nome della cartella sia il prefisso dell'URL
compilato (docs/i18n/es/guides/setup.md → /es/guides/setup/), quindi
tienilo breve - un semplice codice lingua (es, fr) o una coppia
lingua-regione (pt-BR, zh-Hans) funzionano entrambi, solo
lettere/cifre/trattini. Il tuo albero docs/ regolare è sempre la
locale predefinita, compilata senza prefisso alla radice del sito
esattamente come oggi - aggiungere docs/i18n/ non cambia nulla al
riguardo.
Assegna a ogni locale un'etichetta di visualizzazione (e, per una lingua
scritta da destra a sinistra, la propria direzione) in bxsites.json:
{
"i18n": {
"defaultLocale": { "code": "en", "label": "English" },
"locales": [
{ "code": "es", "label": "Español" },
{ "code": "ar", "label": "العربية", "dir": "rtl" },
{ "code": "pt-BR", "label": "Português (Brasil)", "flag": "🇧🇷" }
]
}
}
defaultLocale va impostato solo se la tua locale predefinita non è
l'inglese; locales è l'elenco di tutto il resto. Ogni cartella
docs/i18n/<code>/ si compila automaticamente non appena esiste -
locales fornisce solo la sua etichetta di visualizzazione e direzione
del testo. Una cartella senza una voce corrispondente in locales si
compila comunque (usando il proprio codice nudo come propria etichetta),
quindi questi sono metadati, non ciò che attiva o disattiva la
funzionalità.
flag è opzionale - il selettore sceglie già da sé un'emoji bandiera
sensata per una quarantina di codici lingua comuni (controllando prima un
codice regione come pt-BR, poi ricadendo sulla lingua base pt).
Imposta flag tu stesso solo per correggere quell'ipotesi, oppure per un
codice che la ricerca integrata non riconosce (in quel caso ricade su un
semplice 🌐).
Cosa viene compilato
Ogni locale è una compilazione vera e completamente indipendente - il
proprio search-index.json, i propri assets/, tutto ciò che produce
una compilazione normale - scritta sotto site/<code>/ (site/es/,
site/ar/). Non serve attivare nulla per locale: una volta che esiste
docs/i18n/es/, bxSites build la recepisce da sé.
Pagine non tradotte
Una locale non ha bisogno che ogni pagina sia tradotta prima di essere
utilizzabile. Una pagina mancante da docs/i18n/es/ si compila comunque
al proprio URL previsto - mostrando il contenuto della locale
predefinita, con un piccolo avviso in cima alla pagina che segnala che
non è ancora stata tradotta. Niente restituisce 404, niente sembra a metà
mentre una traduzione è in corso.
La nav di ogni locale ha sempre esattamente la stessa forma di quella
della locale predefinita - stesse pagine, stesso ordine, stesso
annidamento (qualunque cosa produca già la struttura di cartelle propria
di docs/, o una nav esplicita) - solo con
il titolo/contenuto di ogni pagina sostituiti dalla propria traduzione
dove esiste. Questo è anche ciò che fa funzionare il selettore di lingua:
cambiare lingua ti porta sulla stessa pagina, tradotta o no, mai sulla
home page di quella locale.
Il selettore di lingua
Non appena esiste più di una locale, ogni tema renderizza automaticamente un menu a discesa della lingua con icona bandiera nell'header - niente da attivare esplicitamente, come per il selettore di versione. Mostra la bandiera della locale corrente come attivatore; aprendolo elenca ogni locale con la propria bandiera ed etichetta, quella corrente segnata come attiva. Scegli una locale che non stai attualmente compilando e semplicemente non verrà renderizzata affatto.
Documenti versionati e tradotti
Vedi Versionamento per docs/versions/<name>/ in sé.
Versioni e locale si combinano su un livello: metti una cartella
docs/versions/<name>/i18n/<code>/ accanto alle pagine proprie di una
versione, rispecchiando esattamente la struttura di quella versione allo
stesso modo in cui un docs/i18n/<code>/ di primo livello rispecchia
docs/ stesso:
docs/
versions/
2.0/
index.md
guides/
setup.md
i18n/
es/
index.md # tradotto
guides/
setup.md # pagine non tradotte ricadono comunque, come al primo livello
Questo compila site/versions/2.0/es/. Le pagine della locale
predefinita proprie di una versione (site/versions/2.0/) ottengono
anch'esse un selettore di lingua, che elenca solo le locale per cui
quella versione stessa ha traduzioni - una versione senza una propria
sottocartella i18n/ viene renderizzata esattamente come prima che
questo esistesse, nessun selettore mostrato. Cambiare versione ricade
sempre sulla locale predefinita propria di quella versione (non
presuppone mai che la versione di destinazione abbia la stessa
traduzione); cambiare locale resta sempre sulla versione corrente.
Cosa è fuori scopo (per ora)
- Gli elementi di contorno del tema restano in inglese. "Edit this page," "Last updated," il placeholder della ricerca, e stringhe di UI simili non sono ancora tradotte per locale - solo il contenuto delle tue pagine lo è. L'esperienza di lettura effettiva di una locale è completamente tradotta; gli elementi di contorno del tema no.
- Lo specchiamento del layout RTL è di base, non pixel-perfect.
dir="rtl"viene impostato correttamente, e la barra laterale/header vengono effettivamente specchiati, ma alcuni dettagli decorativi (il lato della barra d'accento di un'ammonizione, per esempio) non si invertono ancora. - Nessuna traduzione automatica. Ogni file
docs/i18n/<code>/è scritto a mano, come qualsiasi altra pagina markdown - non c'è alcun passaggio di traduzione automatica.
Icone e include personalizzati
Un riferimento a icona custom: e un ::: include si risolvono entrambi
rispetto a docs/assets//contenuto riutilizzabile propri del tuo
progetto, indipendentemente da quale locale si stia compilando - questi
sono asset condivisi, non qualcosa che un traduttore deve duplicare per
locale.
SEO
Le pagine di ogni locale sono incluse in sitemap.xml e llms.txt
insieme a quelle della locale predefinita, allo stesso modo in cui lo
sono le pagine versionate.