Autore:
    Aymeric PINEAU
    Creazione:2024-03-07Ultimo aggiornamento:2026-08-30

    Tradurre il tuo sito Astro con Intlayer | Internazionalizzazione (i18n)

    ide.intlayer.org
    intlayer-astro-template.vercel.app

    Indice

    Perché Intlayer rispetto alle alternative?

    Rispetto alle soluzioni principali come astro-i18n o i18next, Intlayer è una soluzione dotata di ottimizzazioni integrate come:

    Intlayer è ottimizzato per funzionare perfettamente con Astro offrendo routing multilingue, mappa del sito e tutte le funzionalità necessarie per scalare l'internazionalizzazione (i18n).

    Invece di caricare enormi file JSON nelle tue pagine, carica solo il contenuto necessario. Intlayer aiuta a ridurre le dimensioni del bundle e della pagina fino al 50%.

    L'ambito del contenuto dell'applicazione facilita la manutenzione per applicazioni su larga scala. Puoi duplicare o eliminare una singola cartella di funzionalità senza l'onere mentale di rivedere l'intera codebase dei contenuti. Inoltre, Intlayer è completamente tipizzato (fully typed) per garantire l'accuratezza dei tuoi contenuti.

    La co-localizzazione dei contenuti riduce il contesto necessario dai Large Language Models (LLM). Intlayer viene fornito anche con una suite di strumenti, come una CLI per verificare le traduzioni mancanti,LSP, MCP e agent skills, per rendere l'esperienza dello sviluppatore (DX) ancora più fluida per gli agenti IA.

    Utilizza l'automazione per tradurre nella tua pipeline CI/CD utilizzando il LLM di tua scelta al costo del tuo provider di intelligenza artificiale. Intlayer offre anche un compilatore per automatizzare l'estrazione dei contenuti, nonché una piattaforma web per aiutare a tradurre in background.

    La connessione di enormi file JSON ai componenti può portare a problemi di prestazioni e reattività. Intlayer ottimizza il caricamento dei contenuti in fase di compilazione.

    Più di una semplice soluzione i18n, Intlayer fornisce un editor visivo self-hosted e un CMS completo per aiutarti gestisci i tuoi contenuti multilingue in tempo reale, semplificando la collaborazione con traduttori, copywriter e altri membri del team. I contenuti possono essere archiviati localmente e/o in remoto.

    Guida passo dopo passo per configurare Intlayer in Astro

    Controlla il template dell'applicazione su GitHub.

    1. Installare le dipendenze

      Installa i pacchetti necessari utilizzando il tuo gestore di pacchetti preferito:

      bash
      npx intlayer init --interactive
      il flag --interactive è opzionale. Usa intlayer-cli init se sei un agente AI.
      Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Per esempio:
      bash
      npm install intlayer astro-intlayer

      • intlayer Il pacchetto core che fornisce strumenti i18n per la gestione della configurazione, le traduzioni, la dichiarazione dei contenuti, la transpilazione e i comandi CLI.

      • astro-intlayer Include il plugin di integrazione Astro per collegare Intlayer con il bundler Vite, oltre al middleware per rilevare la lingua preferita dell'utente, gestire i cookie e gestire i reindirizzamenti degli URL.

    2. Configura il tuo progetto

      Crea un file di configurazione per definire le lingue della tua applicazione:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      Locales.ITALIAN,
      // Le tue altre lingue
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      Attraverso questo file di configurazione, puoi configurare URL localizzati, reindirizzamenti del middleware, nomi dei cookie, posizione ed estensioni delle dichiarazioni di contenuto, disabilitare i log di Intlayer nella console e altro ancora. Per un elenco completo dei parametri disponibili, consulta la documentazione di configurazione.

    3. Integra Intlayer nella tua configurazione Astro

      Aggiungi il plugin intlayer alla tua configurazione Astro.

      astro.config.ts
      // @ts-check

import { intlayer } from "astro-intlayer";
import { defineConfig } from "astro/config";

// https://astro.build/config
export default defineConfig({
  integrations: [intlayer()],
});
      Il plugin di integrazione intlayer() viene utilizzato per integrare Intlayer con Astro. Garantisce la generazione dei file di dichiarazione del contenuto e li monitora in modalità sviluppo. Definisce le variabili d'ambiente di Intlayer all'interno dell'applicazione Astro e fornisce alias per ottimizzare le prestazioni.

    4. Dichiara i tuoi contenuti

      Crea e gestisci le tue dichiarazioni di contenuto per memorizzare le traduzioni:

      src/app.content.tsx
      import { t, type Dictionary } from "intlayer";
import type { ReactNode } from "react";

const appContent = {
  key: "app",
  content: {
    title: t({
      en: "Hello World",
      fr: "Bonjour le monde",
      es: "Hola mundo",
      it: "Ciao mondo",
    }),
  },
} satisfies Dictionary;

export default appContent;
      Le dichiarazioni di contenuto possono essere definite in qualsiasi punto della tua applicazione, purché siano incluse nel contentDir (per impostazione predefinita ./src) e corrispondano all'estensione dei file di dichiarazione del contenuto (per impostazione predefinita .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Per ulteriori informazioni, consulta la documentazione sulla dichiarazione del contenuto.

    5. Utilizzare il contenuto in Astro

      Puoi consumare i dizionari direttamente nei tuoi file .astro utilizzando gli helper core esportati da intlayer.

      src/pages/index.astro
      ---
import {
  getIntlayer,
  getLocaleFromPath,
  getLocalizedUrl,
  defaultLocale,
  localeMap,
  getHTMLTextDir,
  type LocalesValues,
} from "intlayer";
import LocaleSwitcher from "../components/LocaleSwitcher.astro";

// Get the current locale from the URL (e.g. /es/about -> 'es')
const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;

// Get the content for the 'app' dictionary
const { title } = getIntlayer("app", locale);
---

<!doctype html>
<html lang={locale} dir={getHTMLTextDir(locale)}>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <title>{title}</title>

    <!-- Canonical link: Tells search engines which is the primary version of this page -->
    <link
      rel="canonical"
      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
    />

    <!-- Hreflang: Tell Google about all localized versions -->
    {
      localeMap(({ locale: mapLocale }) => (
        <link
          rel="alternate"
          hreflang={mapLocale}
          href={new URL(
            getLocalizedUrl(Astro.url.pathname, mapLocale),
            Astro.site
          )}
        />
      ))
    }

    <!-- x-default: Fallback for users in unmatched languages -->
    <link
      rel="alternate"
      hreflang="x-default"
      href={new URL(
        getLocalizedUrl(Astro.url.pathname, defaultLocale),
        Astro.site
      )}
    />
  </head>
  <body>
    <header>
      <LocaleSwitcher />
    </header>
    <main>
      <h1>{title}</h1>
    </main>
  </body>
</html>

    6. Routing localizzato

      Crea segmenti di percorso dinamici per servire le pagine localizzate (ad esempio, src/pages/[locale]/index.astro):

      src/pages/[locale]/index.astro
      ---
import { getIntlayer } from "intlayer";

const { title } = getIntlayer('app');
---

<h1>{title}</h1>

      L'integrazione Astro aggiunge un middleware Vite che aiuta con il routing sensibile alla lingua e le definizioni d'ambiente durante lo sviluppo. Puoi anche creare collegamenti tra lingue diverse utilizzando la tua logica o strumenti intlayer come getLocalizedUrl.

    7. Aggiungere un selettore di lingua

      Per consentire gli utenti di cambiare lingua, puoi creare un componente LocaleSwitcher. Questo componente dovrebbe mostrare un elenco di tutte le lingue supportate e collegarsi alla stessa pagina in ciascuna lingua.

      src/components/LocaleSwitcher.astro
      ---
import {
  locales,
  getLocaleName,
  getLocalizedUrl,
  getLocaleFromPath,
  getPathWithoutLocale,
  type LocalesValues,
} from "intlayer";

const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
---

<nav>
  {
    locales.map((localeItem) => (
      <a
        href={getLocalizedUrl(pathWithoutLocale, localeItem)}
        data-locale={localeItem}
        aria-current={localeItem === locale ? "page" : undefined}
      >
        {getLocaleName(localeItem)}
      </a>
    ))
  }
</nav>

<script>
  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";

  const localeLinks = document.querySelectorAll("[data-locale]");

  localeLinks.forEach((link) => {
    link.addEventListener("click", (e) => {
      const locale = link.getAttribute("data-locale") as LocalesValues;

      // Update the locale cookie
      setLocaleInStorageClient(locale);
    });
  });
</script>

<style>
  nav {
    display: flex;
    gap: 1rem;
  }
  a[aria-current="page"] {
    font-weight: bold;
    text-decoration: underline;
  }
</style>

      Nota sulla persistenza: L'uso di setLocaleInStorageClient nello script lato client assicura che la preferenza della lingua dell'utente sia salvata in un cookie. Ciò consente al middleware Intlayer di ricordare la scelta e reindirizzare automaticamente l'utente alla sua lingua preferita nelle visite future.

    8. Sitemap e Robots.txt

      Intlayer offre utilità per creare dinamicamente la tua sitemap localizzata e i file robots.txt.

      Sitemap

      Intlayer include un generatore di sitemap integrato per aiutarti a creare facilmente una sitemap per la tua applicazione. Gestisce i percorsi localizzati e aggiunge i metadati necessari per i motori di ricerca.

      La sitemap generata da Intlayer supporta lo spazio dei nomi xhtml:link (Hreflang XML Extensions). A differenza dei generatori di sitemap predefiniti che elencano solo URL grezzi, Intlayer crea automaticamente i collegamenti bidirezionali richiesti tra tutte le versioni linguistiche di una pagina (ad esempio, /about, /about?lang=fr e /about?lang=es). Ciò garantisce che i motori di ricerca indicizzino e servano correttamente la versione linguistica corretta al pubblico giusto.

      Crea src/pages/sitemap.xml.ts per generare una sitemap che includa tutti i tuoi percorsi localizzati.

      src/pages/sitemap.xml.ts
      import type { APIRoute } from "astro";
import { generateSitemap, type SitemapUrlEntry } from "intlayer";

const pathList: SitemapUrlEntry[] = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";

export const GET: APIRoute = async ({ site }) => {
  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });

  return new Response(xmlOutput, {
    headers: { "Content-Type": "application/xml" },
  });
};

      Robots.txt

      Crea src/pages/robots.txt.ts per controllare la scansione dei motori di ricerca.

      src/pages/robots.txt.ts
      import type { APIRoute } from "astro";
import { getMultilingualUrls } from "intlayer";

const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

export const GET: APIRoute = ({ site }) => {
  const robotsTxt = [
    "User-agent: *",
    "Allow: /",
    ...disallowedPaths.map((path) => `Disallow: ${path}`),
    "",
    `Sitemap: ${new URL("/sitemap.xml", site).href}`,
  ].join("\n");

  return new Response(robotsTxt, {
    headers: { "Content-Type": "text/plain" },
  });
};

    9. Continua a utilizzare i tuoi framework preferiti

      Continua a costruire la tua applicazione utilizzando il framework che preferisci.

    10. Estrarre il contenuto dei tuoi componenti

      Opzionale

      Se hai una base di codice esistente, trasformare migliaia di file può richiedere molto tempo.

      Per facilitare questo processo, Intlayer propone un compilatore / estrattore per trasformare i tuoi componenti ed estrarre il contenuto.

      Per configurarlo, puoi aggiungere una sezione compiler nel tuo file intlayer.config.ts:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Resto della tua configurazione
  compiler: {
    /**
     * Indica se il compilatore deve essere abilitato.
     */
    enabled: true,

    /**
     * Definisce il percorso dei file di output
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Indica se i componenti devono essere salvati dopo essere stati trasformati. In questo modo, il compilatore può essere eseguito solo una volta per trasformare l'app e poi rimosso.
     */
    saveComponents: false,

    /**
     * Prefisso chiave dizionario
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Esegui l'estrattore per trasformare i tuoi componenti ed estrarre il contenuto

      bash
      npx intlayer extract
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

      Aggiorna il tuo vite.config.ts per includere il plugin intlayerCompiler:

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // Adds the compiler plugin
  ],
});
      bash
      npm run build # Oppure npm run dev

    Configurazione TypeScript

    Intlayer utilizza l'aumento dei moduli (module augmentation) per sfruttare TypeScript, rendendo la tua base di codice più robusta.

    Autocompletamento

    Errore di traduzione

    Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

    tsconfig.json
    {
  // ... la tua configurazione TypeScript esistente
  "include": [
    // ... la tua configurazione TypeScript esistente
    ".intlayer/**/*.ts", // Includi i tipi autogenerati
  ],
}

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer. Ciò evita di salvarli nel tuo repository Git.

    Per farlo, aggiungi le seguenti istruzioni al tuo file .gitignore:

    bash
    # Ignora i file generati da Intlayer
.intlayer

    Estensione VS Code

    Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare l'estensione ufficiale Intlayer per VS Code.

    Installa dal VS Code Marketplace

    Questa estensione fornisce:

    • Autocompletamento per le chiavi di traduzione.
    • Rilevamento degli errori in tempo reale per le traduzioni mancanti.
    • Anteprima inline del contenuto tradotto.
    • Azioni rapide per creare e aggiornare facilmente le traduzioni.

    Per maggiori informazioni sull'utilizzo dell'estensione, consulta la documentazione dell'estensione VS Code.

    Approfondisci

    Se vuoi saperne di più, puoi anche implementare il Visual Editor o utilizzare il CMS per esternalizzare i tuoi contenuti.

    Domande frequenti

    Astro include un'opzione i18n a livello di routing che gestisce i prefissi di locale e i reindirizzamenti, ma non gestisce il contenuto stesso, quindi ti serve comunque un livello di messaggi:

    • L'i18n integrato di Astro più dizionari JSON o TypeScript scritti a mano: nessuna dipendenza, ma nessuna tipizzazione, nessuna regola di plurale e nessuno strumento.
    • i18next o vue-i18n / svelte-i18n all'interno delle island: una libreria completa per framework di island, ciascuna con il proprio catalogo.
    • Intlayer: un unico livello di contenuto condiviso dalle pagine Astro e da ogni framework di island, compilato in fase di build, completamente tipizzato, con traduzione AI, un editor visivo e un CMS.

    Il vantaggio specifico di Astro è che lo stesso dizionario serve una pagina .astro e un'island React, Vue, Svelte, Solid, Preact o Lit, invece di una libreria i18n per runtime di island. Vedi perché Intlayer.

    Molto meno di una configurazione basata su namespace, perché una pagina non scarica mai un catalogo che non renderizza. Le pagine Astro sono renderizzate in fase di build, quindi inviano HTML tradotto e nessun dizionario; solo le island ne ricevono uno. Il compilatore in fase di build risolve le chiamate di contenuto alle esatte voci che un componente utilizza, e i dizionari dinamici suddividono il resto per locale. Misurato rispetto alle alternative abituali, Intlayer riduce la dimensione del bundle e delle pagine fino al 50%. Vedi ottimizzazione del bundle e il benchmark.

    In gran parte. Segui la guida alla migrazione da i18next per spostare il contenuto. Puoi anche migrare gradualmente: il plugin di sincronizzazione JSON mantiene i tuoi cataloghi JSON esistenti come fonte di verità e genera dizionari Intlayer da essi, così entrambi i livelli restano sincronizzati mentre sposti i componenti uno alla volta.

    Sì. Il plugin di sincronizzazione JSON mantiene i tuoi file /messages/{locale}/{namespace}.json come fonte di verità e genera dizionari Intlayer da essi, in entrambe le direzioni. Un plugin di sincronizzazione PO fa lo stesso per i cataloghi gettext, e i file per locale ti permettono di dividere il contenuto per lingua invece di raggruppare i locale in un unico file.

    No. Esegui npx intlayer extract e Intlayer legge i tuoi componenti, estrae le stringhe visibili all'utente e scrive un file .content accanto a ciascuno, così puoi rivedere un diff invece di copiare le stringhe in un catalogo una alla volta. Il passo 15 di questa guida lo illustra.

    Per una pipeline completamente automatizzata, il Compilatore Intlayer fa lo stesso in fase di build: analizza il tuo codice sorgente JSX, TSX, Vue e Svelte ad ogni modifica, genera i dizionari e li mantiene sincronizzati attraverso l'hot module replacement, così non ci sono affatto chiavi da mantenere a mano.

    Due limiti vale la pena conoscere prima di attivare il compilatore. Funziona per analisi statica, quindi le stringhe che esistono solo a runtime, come i codici di errore delle API o i campi del CMS, restano fuori portata. E deve distinguere il testo visibile all'utente dalla logica applicativa come className="active" o un codice di stato, il che richiede alcune annotazioni in una codebase estesa. Il comando extract evita entrambi mantenendoti nel ciclo.

    Cinque componenti, tutti opzionali:

    • Estensione VS Code: salta da una chiave useIntlayer al file di contenuto che la dichiara, estrai il contenuto da un componente ed esegui build, fill, test, push e pull dalla palette dei comandi o da una scheda Intlayer dedicata.
    • Server LSP: la stessa consapevolezza in qualsiasi editor che parla LSP, con vai alla definizione, trova tutti i riferimenti, anteprime al passaggio del mouse di un valore tradotto, autocompletamento di chiavi e campi, e un avviso quando una chiave non è dichiarata da nessuna parte. Risolve anche le chiamate i18next, react-i18next, next-intl e use-intl, il che aiuta durante la migrazione.
    • Server MCP: espone la documentazione di Intlayer e la CLI a Cursor, VS Code, Claude Desktop, Claude Code e ChatGPT, così un assistente risponde in base alla documentazione aggiornata invece di tirare a indovinare, e può eseguire da solo comandi come intlayer fill.
    • Agent skills: competenze mirate come intlayer-config, intlayer-cli e intlayer-content, più una per framework, che insegnano a un agente la tua configurazione di routing e i tipi di nodo dei contenuti.
    • Plugin ESLint: no-raw-text segnala le stringhe hardcoded, con ulteriori regole per le chiavi statiche dei dizionari e i contenuti non utilizzati.
    Tanstack Start SolidAstro e React