Creation:2026-03-23Last update:2026-05-31

    Traduci il tuo sito web Vite e Vanilla JS utilizzando Intlayer | Internazionalizzazione (i18n)

    ide.intlayer.org

    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 Vite 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 Vite e Vanilla JS

    1. Installa le dipendenze

      Installa i pacchetti necessari utilizzando npm:

      bash
      npm install intlayer vanilla-intlayernpm install vite-intlayer --save-devnpx intlayer init

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

      • vanilla-intlayer Il pacchetto che integra Intlayer con applicazioni JavaScript puro / TypeScript. 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.

      • vite-intlayer Include il plugin Vite per l'integrazione di Intlayer con il bundler Vite, oltre a un middleware per rilevare la lingua preferita dell'utente, gestire i cookie e gestire il reindirizzamento degli URL.

    2. Configurazione del progetto

      Crea un file di configurazione per impostare 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,
      // 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, consulta la documentazione sulla configurazione.

    3. Integra Intlayer nella tua configurazione Vite

      Aggiungi il plugin intlayer nella tua configurazione.

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

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

    4. Bootstrap di Intlayer nel tuo punto di ingresso

      Chiama installIntlayer() prima che qualsiasi contenuto venga renderizzato in modo che il singleton della lingua globale sia pronto.

      src/main.ts
      import { installIntlayer } from "vanilla-intlayer";// Deve essere chiamato prima di renderizzare qualsiasi contenuto i18n.installIntlayer();// Importa ed esegui i tuoi moduli dell'applicazione.import "./app.js";

      Se utilizzi anche dichiarazioni di contenuto md() (Markdown), installa anche il renderer markdown:

      src/main.ts
      import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";installIntlayer();installIntlayerMarkdown();import "./app.js";

    5. Dichiarazione del contenuto

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

      src/app.content.ts
      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: "Fai clic sul logo Vite per saperne di più",
    }),
  },
} satisfies Dictionary;

export default appContent;

      Le tue dichiarazioni dei contenuti possono essere definite ovunque nella tua applicazione, purché 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, consulta la documentazione sulla dichiarazione dei contenuti.

    6. Usa Intlayer nel tuo JavaScript

      vanilla-intlayer rispecchia l'API di superficie di react-intlayer: useIntlayer(key, locale?) restituisce direttamente il contenuto tradotto. Collega .onChange() sul risultato per iscriverti ai cambiamenti di lingua - l'equivalente esplicito di un re-render di React.

      src/main.ts
      import { installIntlayer, useIntlayer } from "vanilla-intlayer";installIntlayer();// Ottieni il contenuto iniziale per la lingua corrente.// Collega .onChange() per essere informato ogni volta che la lingua cambia.const content = useIntlayer("app").onChange((newContent) => {  // Re-render o aggiornamento solo dei nodi DOM interessati  document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(    newContent.title  );  document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =    String(newContent.readTheDocs);});// Render inizialedocument.querySelector<HTMLHeadingElement>("h1")!.textContent = String(  content.title);document.querySelector<HTMLParagraphElement>(".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:

      typescript
      img.alt = content.viteLogoLabel.value;

    7. Cambia la lingua dei tuoi contenuti

      Opzionale

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

      src/locale-switcher.ts
      import { getLocaleName } from "intlayer";import { useLocale } from "vanilla-intlayer";export function setupLocaleSwitcher(container: HTMLElement): () => void {  const { locale, availableLocales, setLocale, subscribe } = useLocale();  const select = document.createElement("select");  select.setAttribute("aria-label", "Language");  const render = (currentLocale: string) => {    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 as any));  // Mantieni il dropdown sincronizzato quando la lingua cambia da altrove  return subscribe((newLocale) => render(newLocale));}

    8. Renderizza contenuti Markdown e HTML

      Opzionale

      Intlayer supporta le dichiarazioni di contenuto md() e html(). In vanilla JS, l'output compilato viene inserito come HTML grezzo tramite innerHTML.

      Compila e inietta l'HTML:

      src/main.ts
      import {  compileMarkdown,  installIntlayerMarkdown,  useIntlayer,} from "vanilla-intlayer";installIntlayerMarkdown();const content = useIntlayer("app").onChange((newContent) => {  const el = document.querySelector<HTMLDivElement>(".edit-note")!;  el.innerHTML = compileMarkdown(String(newContent.editNote));});document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =  compileMarkdown(String(content.editNote));
      TIP
      String(content.editNote) chiama toString() sull'IntlayerNode che restituisce la stringa Markdown grezza. Passala a compileMarkdown per ottenere una stringa HTML, quindi impostala tramite innerHTML.
      WARNING

      Usa innerHTML solo con contenuti fidati. Se il markdown proviene dall'input dell'utente, sanificalo prima (es. con DOMPurify). Puoi installare un renderer di sanificazione dinamicamente:

      typescript
      import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";await installIntlayerMarkdownDynamic(async () => {  const DOMPurify = await import("dompurify");  return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));});

    9. Aggiungi il routing localizzato alla tua applicazione

      Opzionale

      Per creare percorsi unici per ogni lingua (utile per il SEO), puoi utilizzare intlayerProxy nella tua configurazione Vite per il rilevamento della lingua lato server.

      Innanzitutto, aggiungi intlayerProxy alla tua configurazione Vite:

      Tieni presente che per utilizzare intlayerProxy in produzione, devi spostare vite-intlayer da devDependencies a dependencies.
      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayerProxy(), // dovrebbe essere posizionato per primo
    intlayer(),
  ],
});

    10. Cambia l'URL quando cambia la lingua

      Opzionale

      Per aggiornare l'URL del browser quando cambia la lingua, chiama useRewriteURL() dopo aver installato Intlayer:

      src/main.ts
      import { installIntlayer, useRewriteURL } from "vanilla-intlayer";installIntlayer();// Riscrive l'URL immediatamente e ad ogni successivo cambiamento di lingua.// Restituisce una funzione di cancellazione dell'iscrizione per la pulizia.const stopRewriteURL = useRewriteURL();

    11. Passa agli attributi HTML della lingua e della direzione

      Opzionale

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

      src/main.ts
      import { getHTMLTextDir } from "intlayer";import { installIntlayer, useLocale } from "vanilla-intlayer";installIntlayer();useLocale({  onLocaleChange: (locale) => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  },});

    12. Caricamento differito dei dizionari per lingua

      Opzionale

      Per le app di grandi dimensioni potresti voler dividere il dizionario di ogni lingua nel proprio chunk. Usa useDictionaryDynamic insieme all'import() dinamico di Vite:

      src/app.ts
      import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";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);});
      Il bundle di ogni lingua viene recuperato solo quando quella lingua diventa attiva e il risultato viene memorizzato nella cache - i successivi passaggi alla stessa lingua sono istantanei.

    13. Estract 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 config  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 quindi può essere rimosso.     */    saveComponents: false,    /**     * Prefisso della chiave del dizionario     */    dictionaryKeyPrefix: "",  },};export default config;

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

      bash
      npx intlayer extract

    (Opzionale) Sitemap e robots.txt (generazione in build)

    Intlayer espone utilità - generateSitemap e getMultilingualUrls - per formattare sitemap.xml multilingue e robots.txt pronti per i crawler e scriverli automaticamente in public/. Di solito si esegue un piccolo script Node prima di Vite (ad esempio hook npm predev / prebuild) così che i file siano presenti in build o in sviluppo.

    Sitemap

    Il generatore di sitemap di Intlayer rispetta le tue lingue e aggiunge i metadati attesi dai crawler.

    La sitemap supporta lo spazio dei nomi xhtml:link (hreflang). Invece di elencare solo URL “piatti”, Intlayer collega in modo bidirezionale tutte le versioni linguistiche di ogni pagina (ad es. /about, /fr/about o /about?lang=fr a seconda del routing).

    Robots.txt

    Usa getMultilingualUrls così le regole Disallow coprono tutte le varianti localizzate dei percorsi sensibili.

    1. Aggiungi generate-seo.mjs nella root del progetto

    generate-seo.mjs
    import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

    Serve il pacchetto intlayer installato. Imposta SITE_URL in ambiente per la produzione (es. in CI).

    Preferisci generate-seo.mjs per l’ESM di Node. Con generate-seo.js imposta "type": "module" in package.json oppure abilita l’ESM in Node.

    2. Esegui lo script prima di Vite

    package.json
    {  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

    Adatta i comandi se usi pnpm o yarn. Puoi anche richiamare lo script dalla CI o da un altro passo del pipeline.

    Configura TypeScript

    Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

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

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer. Ciò consente di evitare di inserirli nel proprio repository Git.

    Per farlo, puoi aggiungere 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 di 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.
    • Anteprime in linea del contenuto tradotto.
    • Azioni rapide per creare e aggiornare facilmente le traduzioni.

    Per maggiori dettagli su come utilizzare l'estensione, consulta la documentazione dell'estensione Intlayer per VS Code.

    Vai oltre

    Per andare oltre, puoi implementare l'editor visuale o esternalizzare il tuo contenuto utilizzando il CMS.

    Vite e Preact
    Vite e Lit