Internazionalizzazione (i18n)

Starlight offre il supporto per siti multilingua, compreso di indirizzamento, contenuti fallback e completo supporto per lingue scritte da destra a sinistra (RTL).

Configurare i18n

1. Indicare a Starlight le lingue che si vuole supportare passando locales e defaultLocale all’integrazione Starlight:

   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   
   export default defineConfig({
   	integrations: [
   		starlight({
   			title: 'My Docs',
   			// Indica l'inglese come lingua predefinita.
   			defaultLocale: 'en',
   			locales: {
   				// La documentazione in inglese si trova in `src/content/docs/en/`
   				en: {
   					label: 'English',
   				},
   				// La documentazione in cinese semplificato si trova in `src/content/docs/zh-cn/`
   				'zh-cn': {
   					label: '简体中文',
   					lang: 'zh-CN',
   				},
   				// La documentazione in arabo si trova in `src/content/docs/ar/`
   				ar: {
   					label: 'العربية',
   					dir: 'rtl',
   				},
   			},
   		}),
   	],
   });

   Il defaultLocale sarà utilizzato come fallback per contenuti ed interfaccia, quindi scegli il linguaggio per cui c’è più probabilità di iniziare a scrivere o già hai contenuti.

2. Creare una cartella per ogni lingua in src/content/docs/. Per esempio, per la configurazione di sopra:

   • Directorysrc/

     • Directorycontent/

       • Directorydocs/

         • Directoryar/

           • …
         • Directoryen/

           • …
         • Directoryzh-cn/

           • …

3. Puoi ora aggiungere file nelle cartelle. Usa file con lo stesso nome per associare pagine tra i linguaggi e sfruttare le funzionalità di Starlight per i18n, compresi i contenuti di fallback, avvisi di traduzione e altro.

   Per esempio, crea ar/index.md e en/index.md per rappresentare la homepage rispettivamente in arabo e inglese.

Utilizzare una lingua principale

Puoi utilizzare una lingua principale per non avere il prefisso i18n nel percorso. Per esempio, se l’inglese è la lingua principale, un indirizzo sarà del tipo /about invece che /en/about.

Per fare questo, utilizza la chiave root nella configurazione locales. Se la lingua principale è anche la lingua di default rimuovi defaultLocale o impostala a 'root'.

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'My Docs',
			defaultLocale: 'root', // opzionale
			locales: {
				root: {
					label: 'English',
					lang: 'en', // necessario per root
				},
				'zh-cn': {
					label: '简体中文',
					lang: 'zh-CN',
				},
			},
		}),
	],
});

Quando si usa una lingua root, metti le pagine direttamente in src/content/docs/ invece che in una cartella dedicata alla lingua. Per esempio, qui si trovano i file delle pagine per inglese e cinese quando si utilizza la configurazione precedente:

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • index.md
      • Directoryzh-cn/

        • index.md

Siti monolingua

Per default, Starlight è un sito monolingua (inglese). Per creare un sito monolingua in un’altra, impostala come root in locales:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'My Docs',
			locales: {
				root: {
					label: '简体中文',
					lang: 'zh-CN',
				},
			},
		}),
	],
});

Questo ti permette di sovrascrivere le impostazione predefinite di Starlight per la lingua senza abilitare l’internazionalizzazione.

Contenuti fallback

Starlight si aspetta che crei pagine equivalenti per tutte le lingue impostate. Per esempio, se hai un file en/about.md, crea un about.md per ogni altra lingua impostata. Questo permette a Starlight di avere contenuti fallback per le pagine che non hai ancora tradotto.

Se una traduzione non è ancora disponibile per una lingua, Starlight mostrerà ai lettori i contenuti per quella pagina nel linguaggio predefinito (impostato da defaultLocale). Per esempio, se non hai ancora creato una versione italiana della pagina About e la lingua predefinita è inglese, gli utenti per /it/about vedranno i contenuti in inglese di /en/about con un avviso che la pagina non è stata ancora tradotta.

Tradurre l’interfaccia Starlight

In aggiunta alla possibilità di avere pagine multilingua, Starlight permette di tradurre le scritte dell’interfaccia (per esempio l’intestazione “In questa pagina” nella tabella dei contenuti) in modo che i lettori possano vedere il sito interamente nella lingua selezionata.

Le stringhe dell’interfaccia utente tradotte in inglese, ceco, francese, tedesco, italiano, giapponese, portoghese, olandese, danese, spagnolo, turco, arabo, norvegese, farsi, ebraico, cinese semplificato, coreano, indonesiano, russo, svedese e vietnamese sono disponibili di default e accettiamo contributi per aggiungere altre lingue predefinite.

Puoi fornire traduzioni per lingue aggiuntive — o sovrascrivere i valori predefiniti — con la collezione i18n.

1. Configura la collezione i18n in src/content/config.ts se non lo è già:

   // src/content/config.ts
   import { defineCollection } from 'astro:content';
   import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
   
   export const collections = {
   	docs: defineCollection({ schema: docsSchema() }),
   	i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
   };

2. Crea un file JSON in src/content/i18n/ per ogni lingua di cui si vuole fornire la traduzione all’interfaccia. Per esempio, questo aggiungerebbe traduzioni per arabo e cinese semplificato:

   • Directorysrc/

     • Directorycontent/

       • Directoryi18n/

         • ar.json
         • zh-CN.json

3. Aggiungere traduzioni per le chiavi che vuoi tradurre. Traduci solo i valori, le chiavi non devono essere modificate (per esempio "search.label": "Buscar").

   Queste sono le traduzioni di default per l’inglese:

   {
   	"skipLink.label": "Skip to content",
   	"search.label": "Search",
   	"search.shortcutLabel": "(Press / to Search)",
   	"search.cancelLabel": "Cancel",
   	"themeSelect.accessibleLabel": "Select theme",
   	"themeSelect.dark": "Dark",
   	"themeSelect.light": "Light",
   	"themeSelect.auto": "Auto",
   	"languageSelect.accessibleLabel": "Select language",
   	"menuButton.accessibleLabel": "Menu",
   	"sidebarNav.accessibleLabel": "Main",
   	"tableOfContents.onThisPage": "On this page",
   	"tableOfContents.overview": "Overview",
   	"i18n.untranslatedContent": "This content is not available in your language yet.",
   	"page.editLink": "Edit page",
   	"page.lastUpdated": "Last updated:",
   	"page.previousLink": "Next",
   	"page.nextLink": "Previous",
   	"404.text": "Page not found. Check the URL or try using the search bar."
   }

   Il pannello di ricerca di Starlight è basato sulla libreria Pagefind. Puoi impostare le traduzioni per l’interfaccia utente di Pagefind nello stesso file JSON utilizzando le chiavi pagefind”:

   {
   	"pagefind.clear_search": "Clear",
   	"pagefind.load_more": "Load more results",
   	"pagefind.search_label": "Search this site",
   	"pagefind.filters_label": "Filters",
   	"pagefind.zero_results": "No results for [SEARCH_TERM]",
   	"pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
   	"pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
   	"pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
   	"pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
   	"pagefind.searching": "Searching for [SEARCH_TERM]..."
   }