Creazione:2026-03-31Ultimo aggiornamento:2026-05-31

    Traduci il tuo sito web Vanilla JS usando Intlayer | Internazionalizzazione (i18n)

    Sommario

    Perché Intlayer rispetto alle alternative?

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

    Intlayer è ottimizzato per funzionare perfettamente con Vanilla JavaScript offrendo gestione dei contenuti indipendente dal framework, supporto TypeScript 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-passo per configurare Intlayer in un'applicazione Vanilla JS

    1. Installazione delle dipendenze

      Installa i pacchetti necessari utilizzando npm:

      # Genera un bundle standalone di intlayer e vanilla-intlayer
# Questo file verrà importato nel tuo file HTML
npx intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inizializza intlayer con il file di configurazione
npx intlayer init --no-gitignore

# Costruisci i dizionari
npx intlayer build
      # Genera un bundle standalone di intlayer e vanilla-intlayer
# Questo file verrà importato nel tuo file HTML
pnpm intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inizializza intlayer con il file di configurazione
pnpm intlayer init --no-gitignore

# Costruisci i dizionari
pnpm intlayer build
      # Genera un bundle standalone di intlayer e vanilla-intlayer
# Questo file verrà importato nel tuo file HTML
yarn intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inizializza il file di configurazione intlayer, TypeScript se impostato, variabili d'ambiente
yarn intlayer init --no-gitignore

# Costruisci i dizionari
yarn intlayer build
      # Genera un bundle standalone di intlayer e vanilla-intlayer
# Questo file verrà importato nel tuo file HTML
bun x intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inizializza intlayer con il file di configurazione
bun x intlayer init --no-gitignore

# Costruisci i dizionari
bun x intlayer build

      • intlayer Il pacchetto principale che fornisce strumenti di internazionalizzazione per la gestione della configurazione, traduzione, dichiarazione dei contenuti, transpilazione e comandi CLI.

      • vanilla-intlayer Il pacchetto che integra Intlayer con applicazioni JavaScript / TypeScript pure. Fornisce un singleton pub/sub (IntlayerClient) e helper basati su callback (useIntlayer, useLocale, ecc.) in modo che qualsiasi parte della tua app possa reagire ai cambiamenti di lingua senza dipendere da un framework UI.

      L'esportazione del raggruppamento (bundling) della CLI intlayer standalone produce una build ottimizzata mediante il tree-shaking dei pacchetti non utilizzati, delle lingue e della logica non essenziale (come reindirizzamenti o prefissi) specifica per la tua configurazione.

    2. Configurazione del progetto

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

      import { Locales, type IntlayerConfig } from "intlayer";

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

export default config;
      Attraverso questo file di configurazione, puoi impostare URL localizzati, reindirizzamento middleware, nomi dei cookie, la posizione e l'estensione delle tue dichiarazioni di contenuto, disabilitare i log di Intlayer nella console e altro ancora. Per un elenco completo dei parametri disponibili, fai riferimento alla documentazione di configurazione.

    3. Importare il bundle nel tuo HTML

      Una volta generato il bundle intlayer.js, puoi importarlo nel tuo file HTML:

      <!DOCTYPE html>
<html lang="it">
  <head>
    <meta charset="UTF-8" />

    <!-- Importa il bundle -->
    <script src="./intlayer.js" defer></script>
    <!-- Importa il tuo script principale -->
    <script src="./src/main.js" defer></script>
  </head>
  <body>
    <h1 id="title"></h1>
    <p class="read-the-docs"></p>
  </body>
</html>

      Il bundle espone Intlayer e VanillaIntlayer come oggetti globali su window.

    4. Bootstrap Intlayer nel tuo punto di ingresso

      Nel tuo src/main.js, chiama installIntlayer() prima che venga renderizzato qualsiasi contenuto, in modo che il singleton globale della lingua sia pronto.

      const { installIntlayer } = window.VanillaIntlayer;

// Deve essere chiamato prima di renderizzare qualsiasi contenuto i18n.
installIntlayer();

      Se vuoi anche usare il renderer markdown, chiama installIntlayerMarkdown():

      const { installIntlayer, installIntlayerMarkdown } = window.VanillaIntlayer;

installIntlayer();
installIntlayerMarkdown();

    5. Dichiarare il Contenuto

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

      import { insert, t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Vanilla",

    viteLogoLabel: t({
      en: "Vite Logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),

    count: insert(
      t({
        en: "count is {{count}}",
        fr: "le compte est {{count}}",
        es: "el recuento es {{count}}",
      })
    ),

    readTheDocs: t({
      en: "Click on the Vite logo to learn more",
      fr: "Cliquez sur le logo Vite pour en savoir plus",
      es: "Haga clic en el logotipo de Vite para obtener più informazioni",
    }),
  },
} satisfies Dictionary;

export default appContent;
      {
  "$schema": "https://intlayer.org/schema.json",
  "key": "app",
  "content": {
    "title": "Vite + Vanilla",
    "viteLogoLabel": {
      "nodeType": "translation",
      "translation": {
        "en": "Vite Logo",
        "fr": "Logo Vite",
        "es": "Logo Vite"
      }
    },
    "count": {
      "nodeType": "insertion",
      "insertion": {
        "nodeType": "translation",
        "translation": {
          "en": "count is {{count}}",
          "fr": "le compte est {{count}}",
          "es": "el recuento es {{count}}"
        }
      }
    },
    "readTheDocs": {
      "nodeType": "translation",
      "translation": {
        "en": "Click on the Vite logo to learn more",
        "fr": "Cliquez sur le logo Vite pour en savoir plus",
        "es": "Haga clic en el logotipo de Vite para obtener más información"
      }
    }
  }
}

      Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione a patto che siano incluse nella directory contentDir (per impostazione predefinita, ./src). E corrispondano all'estensione del file di dichiarazione del contenuto (per impostazione predefinita, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

      Per maggiori dettagli, fai riferimento alla documentazione sulla dichiarazione dei contenuti.

    6. Utilizzare Intlayer nel tuo JavaScript

      L'oggetto window.VanillaIntlayer fornisce helper API: useIntlayer(key, locale?) restituisce il contenuto tradotto per una data chiave.

      const { installIntlayer, useIntlayer } = window.VanillaIntlayer;

installIntlayer();

// Ottieni il contenuto iniziale per la lingua corrente.
// Concatena .onChange() per essere avvisato ogni volta che la lingua cambia.
const content = useIntlayer("app").onChange((newContent) => {
  // Esegui il re-render o patcha solo i nodi DOM interessati
  document.querySelector("h1").textContent = String(newContent.title);
  document.querySelector(".read-the-docs").textContent = String(
    newContent.readTheDocs
  );
});

// Rendering iniziale
document.querySelector("h1").textContent = String(content.title);
document.querySelector(".read-the-docs").textContent = String(
  content.readTheDocs
);

      Accedi ai valori finali come stringhe avvolgendoli in String(), che chiama il metodo toString() del nodo e restituisce il testo tradotto.

      Quando hai bisogno del valore per un attributo HTML nativo (es. alt, aria-label), usa direttamente .value:

      img.alt = content.viteLogoLabel.value;

    7. Cambiare la lingua del tuo contenuto

      Opzionale

      Per cambiare la lingua del tuo contenuto, usa la funzione setLocale esposta da useLocale.

      const { getLocaleName } = window.Intlayer;
const { useLocale } = window.VanillaIntlayer;

export function setupLocaleSwitcher(container) {
  const { locale, availableLocales, setLocale, subscribe } = useLocale();

  const select = document.createElement("select");
  select.setAttribute("aria-label", "Lingua");

  const render = (currentLocale) => {
    select.innerHTML = availableLocales
      .map(
        (loc) =>
          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>
            ${getLocaleName(loc)}
          </option>`
      )
      .join("");
  };

  render(locale);
  container.appendChild(select);

  select.addEventListener("change", () => setLocale(select.value));

  // Mantieni il menu a discesa sincronizzato quando la lingua cambia da altrove
  return subscribe((newLocale) => render(newLocale));
}

    8. Cambiare gli attributi HTML di lingua e direzione

      Opzionale

      Aggiorna gli attributi lang e dir del tag <html> per corrispondere alla lingua corrente per l'accessibilità e la SEO.

      const { getHTMLTextDir } = window.Intlayer;
const { installIntlayer, useLocale } = window.VanillaIntlayer;

installIntlayer();

useLocale({
  onLocaleChange: (locale) => {
    document.documentElement.lang = locale;
    document.documentElement.dir = getHTMLTextDir(locale);
  },
});

    9. Caricamento lazy dei dizionari per lingua

      Opzionale

      Se desideri caricare i dizionari in modo lazy per lingua, puoi usare useDictionaryDynamic. Questo è utile se non vuoi raggruppare tutte le traduzioni nel file iniziale intlayer.js.

      const { installIntlayer, useDictionaryDynamic } = window.VanillaIntlayer;

installIntlayer();

const unsubscribe = useDictionaryDynamic(
  {
    en: () => import("../.intlayer/dictionaries/en/app.mjs"),
    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),
    es: () => import("../.intlayer/dictionaries/es/app.mjs"),
  },
  "app"
).onChange((content) => {
  document.querySelector("h1").textContent = String(content.title);
});

      Nota: useDictionaryDynamic richiede che i dizionari siano disponibili come file ESM separati. Questo approccio viene in genere utilizzato se si dispone di un server web che serve i dizionari.

    Configurare TypeScript

    Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

    {
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

    Estensione VS Code

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

    Installa dal Marketplace di VS Code

    Questa estensione fornisce:

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

    Per maggiori dettagli su come utilizzare l'estensione, fai riferimento alla documentazione dell'estensione Intlayer per VS Code.

    Vai oltre

    Per approfondire, puoi implementare l'editor visuale o esternalizzare i tuoi contenuti utilizzando il CMS.

    Perché Intlayer?