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

    Traduci il tuo sito web Vite e Lit usando Intlayer | Internazionalizzazione (i18n)

    ide.intlayer.org

    Sommario

    Perché Intlayer rispetto alle alternative?

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

    Intlayer è ottimizzato per funzionare perfettamente con Lit offrendo ambito del contenuto a livello di componente Web, supporto TypeScript e tutte le funzionalità necessarie per ridimensionare 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 Lit

    1. Installare le dipendenze

      Installa i pacchetti necessari utilizzando npm:

      bash
      npm install intlayer lit-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.

      • lit-intlayer Il pacchetto che integra Intlayer con le applicazioni Lit. Fornisce hook basati su ReactiveController (useIntlayer, useLocale, ecc.) in modo che i LitElement si ri-renderizzino automaticamente quando la lingua cambia.

      • vite-intlayer Include il plugin Vite per integrare Intlayer con il bundler Vite, oltre al 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,
      // 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. Integrare Intlayer nella configurazione di 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 dei contenuti e li monitora in modalità di sviluppo. Definisce le variabili d'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 vengano registrati elementi personalizzati, in modo che il singleton globale della lingua sia pronto quando il primo elemento si connette.

      src/main.ts
      import { installIntlayer } from "lit-intlayer";// Deve essere chiamato prima che qualsiasi LitElement sia connesso al DOM.installIntlayer();// Importa e registra i tuoi elementi personalizzati.import "./my-element.js";

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

      src/main.ts
      import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";

    5. Dichiarare il contenuto

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

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

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

    viteLogo: t({
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    litLogo: t({
      en: "Lit logo",
      fr: "Logo Lit",
      es: "Logo Lit",
    }),

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

    readTheDocs: t({
      en: "Click on the Vite and Lit logos to learn more",
      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

      Le dichiarazioni di contenuto possono essere definite ovunque nell'applicazione, purché siano incluse nella cartella 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 ulteriori dettagli, consulta la documentazione sulla dichiarazione dei contenuti.

    6. Utilizzare Intlayer nel tuo LitElement

      Usa useIntlayer all'interno di un LitElement. Restituisce un proxy ReactiveController che attiva automaticamente i re-render ogni volta che la lingua attiva cambia: non è richiesta alcuna configurazione aggiuntiva.

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement, property } from "lit/decorators.js";import { useIntlayer } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  @property({ type: Number })  count = 0;  // useIntlayer si registra come ReactiveController.  // L'elemento si ri-renderizza automaticamente quando la lingua cambia.  private content = useIntlayer(this, "app");  override render() {    const { content } = this;    return html`      <h1>${content.title}</h1>      <img src="/vite.svg" alt=${content.viteLogo.value} />      <img src="/lit.svg" alt=${content.litLogo.value} />      <button @click=${() => this.count++}>        ${content.count({ count: this.count })}      </button>      <p>${content.readTheDocs}</p>    `;  }}

      Quando hai bisogno della stringa tradotta in un attributo HTML nativo (es. alt, aria-label, title), chiama .value sul nodo foglia:

      typescript
      html`<img alt=${content.viteLogo.value} />`;html`<img alt=${content.viteLogo.toString()} />`;html`<img alt=${String(content.viteLogo)} />`;

    7. Cambiare la lingua del contenuto

      Opzionale

      Per cambiare la lingua del contenuto, usa il metodo setLocale esposto dal controller useLocale.

      src/locale-switcher.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

    8. Renderizzare contenuti Markdown e HTML

      Opzionale

      Intlayer supporta le dichiarazioni di contenuto md() e html(). In Lit, l'output compilato viene iniettato come HTML grezzo tramite la direttiva unsafeHTML.

      Renderizza l'HTML compilato nel tuo elemento:

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { unsafeHTML } from "lit/directives/unsafe-html.js";import { useIntlayer } from "lit-intlayer";import { compileMarkdown } from "lit-intlayer/markdown";@customElement("my-element")export class MyElement extends LitElement {  private content = useIntlayer(this, "app");  override render() {    return html`      <div class="edit-note">        ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}      </div>    `;  }}
      TIP
      String(content.editNote) chiama toString() sull'IntlayerNode, che restituisce la stringa Markdown grezza. Passala a compileMarkdown per ottenere una stringa HTML, quindi caricala con la direttiva unsafeHTML di Lit.

    9. Aggiungere il routing localizzato alla tua applicazione

      Opzionale

      Per creare rotte uniche per ogni lingua (utile per la SEO), puoi utilizzare un router lato client insieme agli helper localeMap / localeFlatMap di Intlayer e al plugin Vite intlayerProxy per il rilevamento della lingua lato server.

      Innanzitutto, aggiungi intlayerProxy alla tua configurazione Vite:

      Nota 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(), // should be placed first
    intlayer(),
  ],
});

    10. Cambiare l'URL quando la lingua cambia

      Opzionale

      Per aggiornare l'URL del browser quando la lingua cambia, utilizza useRewriteURL insieme al selettore di lingua:

      src/locale-switcher.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale, useRewriteURL } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  // Riscrive automaticamente l'URL corrente quando la lingua cambia.  private _rewriteURL = useRewriteURL(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

    11. Commutare gli attributi di lingua e direzione HTML

      Opzionale

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

      src/my-element.ts
      import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getHTMLTextDir } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  private locale = useLocale(this, {    onLocaleChange: (loc) => {      document.documentElement.lang = loc;      document.documentElement.dir = getHTMLTextDir(loc);    },  });  override render() {    return html`<!-- il tuo contenuto -->`;  }}

    12. 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 una sola volta per trasformare l'app e poi può essere rimosso.     */    saveComponents: false,    /**     * Prefisso della chiave del dizionario     */    dictionaryKeyPrefix: "",  },};export default config;

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

    Configurare TypeScript

    Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

    tsconfig.json
    {  "compilerOptions": {    // ...    "experimentalDecorators": true,    "useDefineForClassFields": false,  },  "include": ["src", ".intlayer/**/*.ts"],}
    experimentalDecorators e useDefineForClassFields: false sono richiesti da Lit per il supporto dei decoratori.

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer. Ciò consente di evitare di caricarli nel 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 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 inline 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 approfondire, puoi implementare l'editor visuale o esternalizzare i tuoi contenuti utilizzando il CMS.

    Vite e Vanilla JS
    Angular 21