Creation:2026-04-24Last update:2026-05-31

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

    ide.intlayer.org

    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 capacità dell'agente, 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 + Lit

    Controlla il template dell'applicazione su GitHub.

    1. Installare le dipendenze

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

      bash
      npm install intlayer astro-intlayer lit lit-intlayer @astrojs/litnpx intlayer init

      • 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.

      • lit Il pacchetto core di Lit per la creazione di Web Components veloci e leggeri.

      • lit-intlayer Pacchetto per integrare Intlayer in applicazioni Lit. Fornisce hook basati su ReactiveController (useIntlayer, useLocale, ecc.) che istruiscono automaticamente il LitElement a rieseguire il rendering quando la lingua cambia.

      • @astrojs/lit Integrazione ufficiale di Astro che consente l'uso di Lit custom elements all'interno delle pagine Astro.

    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 e l'integrazione Lit alla tua configurazione Astro.

      astro.config.ts
      // @ts-checkimport { intlayer } from "astro-intlayer";import lit from "@astrojs/lit";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer(), lit()],});
      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.
      L'integrazione lit() consente di utilizzare Lit custom elements all'interno delle pagine Astro.

    4. Dichiara i tuoi contenuti

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

      src/components/lit/app.content.ts
      import { t, type Dictionary } from "intlayer";const litDemoContent = {  key: "lit-demo",  content: {    greeting: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      it: "Ciao mondo",    }),    description: t({      en: "Welcome to my multilingual Astro + Lit site.",      fr: "Bienvenue sur mon site Astro + Lit multilingue.",      es: "Bienvenido a mi sitio Astro + Lit multilingüe.",      it: "Benvenuti nel mio sito Astro + Lit multilingue.",    }),  },} satisfies Dictionary;export default litDemoContent;
      Le dichiarazioni di contenuto possono be 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}).
      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. Dovresti anche aggiungere metadati SEO (come hreflang e link canonici) a ogni pagina. I Lit custom element vengono importati tramite uno <script> client e inseriti nel body.

      src/pages/[...locale]/index.astro
      ---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getHTMLTextDir,  getPrefix,  localeMap,  defaultLocale,  type LocalesValues,} from "intlayer";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const { greeting } = getIntlayer("lit-demo", 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>{greeting}</title>    <!-- Link Canonico -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Link Hreflang -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <!-- Lit Custom Element - riceve la lingua rilevata dal server come proprietà -->    <lit-demo locale={locale}></lit-demo>  </body></html><script>  import "../../components/lit/LitDemo";</script>
      Se desideri utilizzare il tuo contenuto in un attributo stringa, come alt, title, href, aria-label, ecc., puoi utilizzare il valore della funzione, come:
      html
      <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

      Nota sulla configurazione del routing: La struttura delle directory che utilizzi dipende dall'impostazione middleware.routing in intlayer.config.ts:

      • prefix-no-default (predefinito): mantiene la lingua predefinita alla radice (senza prefisso) e aggiunge prefissi alle altre. Usa [...locale] per catturare tutti i casi.
      • prefix-all: tutti gli URL hanno il prefisso della lingua. Puoi usare lo standard [locale] se non hai bisogno di gestire la radice separatamente.
      • search-param o no-prefix: non sono necessarie directory per la lingua. La lingua viene gestita tramite parametri di query o cookie.

    6. Crea un componente Lit Custom Element

      Crea un Lit custom element. Richiama installIntlayer nel connectedCallback utilizzando l'attributo locale basato sul server per inizializzare il singleton di traduzione lato client.

      src/components/lit/LitDemo.ts
      import { LitElement, html } from "lit";import { installIntlayer, useIntlayer, useLocale } from "lit-intlayer";import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";class LitDemo extends LitElement {  static properties = {    locale: { type: String },  };  locale: LocalesValues = "en" as LocalesValues;  private _content = useIntlayer(this, "lit-demo");  private _localeCtrl = useLocale(this, {    onLocaleChange: (newLocale: LocalesValues) => {      window.location.href = getLocalizedUrl(        window.location.pathname,        newLocale      );    },  });  override connectedCallback() {    super.connectedCallback();    // Inizializza con la lingua rilevata dal server    installIntlayer({ locale: this.locale as any });  }  override render() {    const { greeting, description } = this._content;    const {      locale: currentLocale,      availableLocales,      setLocale,    } = this._localeCtrl;    return html`      <div>        <h1>${greeting}</h1>        <p>${description}</p>        <!-- Il selettore di lingua è reso all'interno del LitElement -->        <div class="locale-switcher">          <span class="switcher-label">Cambia lingua:</span>          <div class="locale-buttons">            ${availableLocales.map(              (localeItem) => html`                <button                  class="locale-btn ${localeItem === currentLocale                    ? "active"                    : ""}"                  ?disabled=${localeItem === currentLocale}                  @click=${() => setLocale(localeItem)}                >                  <span class="ls-own-name">${getLocaleName(localeItem)}</span>                  <span class="ls-current-name"                    >${getLocaleName(localeItem, currentLocale)}</span                  >                  <span class="ls-code">${localeItem.toUpperCase()}</span>                </button>              `            )}          </div>        </div>      </div>    `;  }}customElements.define("lit-demo", LitDemo);
      L'attributo locale viene passato dalla pagina Astro (rilevamento lato server) e utilizzato per inizializzare installIntlayer nel connectedCallback, che imposta la lingua iniziale per tutti gli hook ReactiveController all'interno dell'elemento.
      useIntlayer viene registrato come ReactiveController. Richiede automaticamente il re-rendering dell'elemento quando la lingua cambia, quindi non è necessaria alcuna logica di sottoscrizione aggiuntiva.

    7. Aggiungi un selettore di lingua

      La funzionalità di cambio lingua è integrata direttamente all'interno del metodo render() del Lit custom element (vedi passaggio 6 sopra). Utilizza useLocale di lit-intlayer e naviga verso l'URL localizzato quando un utente seleziona una nuova lingua:

      src/components/lit/LitDemo.ts
      // All'interno della classe LitElement, dopo la configurazione di useLocale nel passaggio 6:private _localeCtrl = useLocale(this, {  onLocaleChange: (newLocale: LocalesValues) => {    // Naviga verso l'URL localizzato al cambio di lingua    window.location.href = getLocalizedUrl(window.location.pathname, newLocale);  },});override render() {  const { locale: currentLocale, availableLocales, setLocale } = this._localeCtrl;  return html`    <div class="locale-switcher">      <span class="switcher-label">Cambia lingua:</span>      <div class="locale-buttons">        ${availableLocales.map(          (localeItem) => html`            <button              class="locale-btn ${localeItem === currentLocale ? "active" : ""}"              ?disabled=${localeItem === currentLocale}              @click=${() => setLocale(localeItem)}            >              <span class="ls-own-name">${getLocaleName(localeItem)}</span>              <span class="ls-current-name">${getLocaleName(localeItem, currentLocale)}</span>              <span class="ls-code">${localeItem.toUpperCase()}</span>            </button>          `        )}      </div>    </div>  `;}

      Nota sulla reattività di Lit: useLocale restituisce un ReactiveController. Quando viene chiamato setLocale, il controller richiede automaticamente un re-rendering, aggiornando lo stato del pulsante attivo senza manipolazione manuale del DOM.

      Nota sulla persistenza: L'uso di onLocaleChange per reindirizzare tramite window.location.href assicura che il nuovo URL linguistico venga visitato, consentendo al middleware Intlayer di impostare il cookie della lingua e di ricordare la preferenza dell'utente 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. 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

    Configurazione TypeScript

    Intlayer utilizza l'aumento dei moduli (module augmentation) per sfruttare TypeScript, rendendo la tua base di codice più robusta. Se utilizzi la sintassi dei decoratori, assicura di abilitare experimentalDecorators nelle opzioni del compilatore.

    Autocompletamento

    Errore di traduzione

    Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

    tsconfig.json
    {  compilerOptions: {    // ...    experimentalDecorators: true,    useDefineForClassFields: false, // Richiesto per il supporto dei decoratori in Lit  },  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.

    Astro e Preact
    Astro e Vanilla JS