Internazionalizzazione (i18n)

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

Configurare i18n

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

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 riserva per contenuti ed interfaccia, quindi scegli il linguaggio per cui c’è più probabilità di iniziare a scrivere o già hai contenuti.

Creare una cartella per ogni lingua in src/content/docs/. Per esempio, per la configurazione di sopra:
- Directorysrc/
  - Directorycontent/
    Directorydocs/
    Directoryar/
    …
    Directoryen/
    …
    Directoryzh-cn/
    …
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 riserva, 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'.

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 la lingua principale
        },
        '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:

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 di riserva

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 di riserva 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 che visiteranno /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 arabo, ceco, cinese, cinese (Taiwan), coreano, danese, ebraico, francese, galiziano, giapponese, hindi, indonesiano, inglese, italiano, norvegese bokmål, olandese, persiano, polacco, portoghese, rumeno, russo, spagnolo, svedese, tedesco, turco, ucraino e vietnamita 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.

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

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() }),
};

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

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",
  "search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.",
  "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": "Previous",
  "page.nextLink": "Next",
  "page.draft": "This content is a draft and will not be included in production builds.",
  "404.text": "Page not found. Check the URL or try using the search bar.",
  "aside.note": "Note",
  "aside.tip": "Tip",
  "aside.caution": "Caution",
  "aside.danger": "Danger",
  "fileTree.directory": "Directory",
  "builtWithStarlight.label": "Built with Starlight"
}

I blocchi di codice di Starlight sono gestiti dalla libreria Expressive Code. Puoi impostare le traduzioni per le stringhe dell’interfaccia utente nella stessa file JSON utilizzando le chiavi expressiveCode:

{
  "expressiveCode.copyButtonCopied": "Copied!",
  "expressiveCode.copyButtonTooltip": "Copy to clipboard",
  "expressiveCode.terminalWindowFallbackTitle": "Terminal window"
}

Il modulo di ricerca di Starlight è gestito dalla libreria Pagefind. Puoi impostare le traduzioni per l’interfaccia utente di Pagefind nel medesimo 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]..."
}

Estendere lo schema di traduzione

Aggiungi chiavi personalizzate ai dizionari di traduzione del tuo sito impostando extend nelle opzioni di i18nSchema(). Nell’esempio seguente, viene aggiunta una nuova chiave opzionale custom.label alle chiavi predefinite:

import { defineCollection, z } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
  i18n: defineCollection({
    type: 'data',
    schema: i18nSchema({
      extend: z.object({
        'custom.label': z.string().optional(),
      }),
    }),
  }),
};

Per saperne di più sugli schemi di raccolta dei contenuti, consulta “Definire uno schema di raccolta” nella documentazione di Astro.