--- title: Internazionalizzazione (i18n) order: 8 icon: phosphor-duotone:translate tags: [guide, i18n] --- # Internazionalizzazione (i18n) Traduci la tua documentazione in altre lingue, ognuna con il proprio prefisso URL, il proprio ``, e un selettore di lingua automatico - nessun plugin, nessun passaggio di build separato. ## Aggiungere una locale Il contenuto tradotto vive in `docs/i18n//`, 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 ``` `` 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`: ```json title="bxsites.json" linenums="1" { "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//` 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//` (`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`](../configuration.md#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](../configuration.md#versioning). 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](versioning.md) per `docs/versions//` in sé. Versioni e locale si combinano su un livello: metti una cartella `docs/versions//i18n//` accanto alle pagine proprie di una versione, rispecchiando esattamente la struttura di quella versione allo stesso modo in cui un `docs/i18n//` di primo livello rispecchia `docs/` stesso: ```text title="Struttura di docs/versions/2.0/" linenums="1" 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//` è 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](../configuration.md#versioning).