Autore:
    Aymeric PINEAU
    Creazione:2025-04-18Ultimo aggiornamento:2026-08-30

    Traduci la tua Vite and Solid con Intlayer | Internazionalizzazione (i18n)

    www.youtube.com
    ide.intlayer.org
    intlayer-vite-solid.vercel.app

    Indice

    Perché Intlayer rispetto alle alternative?

    Rispetto alle soluzioni principali come @solid-primitives/i18n o i18next, Intlayer è una soluzione dotata di ottimizzazioni integrate come:

    Intlayer è ottimizzato per funzionare perfettamente con Solid offrendo ambito del contenuto a livello di componente, traduzioni reattive 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-passo per configurare Intlayer in un'applicazione Vite e Solid

    Indice

    1. Installare le dipendenze

      Installa i pacchetti necessari usando npm:

      bash
      npx intlayer init --interactive
      il flag --interactive è opzionale. Usa intlayer-cli init se sei un agente IA.
      Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:
      bash
      npm install intlayer solid-intlayer
npm install vite-intlayer --save-dev

      • intlayer

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

      • vite-intlayer

        Include il plugin Vite per integrare Intlayer con il bundler Vite, oltre a middleware per rilevare la lingua preferita dall'utente, gestire i cookie e gestire il reindirizzamento degli URL.

    2. Configurazione del tuo progetto

      Crea un file di configurazione per configurare 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 localizzazioni
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;
      Attraverso questo file di configurazione, puoi impostare URL localizzati, il reindirizzamento tramite middleware, i 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 di configurazione.

    3. Integra Intlayer nella tua configurazione Vite

      Aggiungi il plugin intlayer nella tua configurazione.

      vite.config.ts
      import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), 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 d'ambiente di Intlayer all'interno dell'applicazione Vite. Inoltre, fornisce alias per ottimizzare le prestazioni.

    4. Dichiara il tuo contenuto

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

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

const appContent = {
  key: "app",
  content: {},
} satisfies Dictionary;

export default appContent;
      Le dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione non appena vengono incluse nella directory contentDir (di default, ./src). E devono corrispondere all'estensione del file di dichiarazione del contenuto (di default, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

    5. Utilizzare Intlayer nel tuo codice

      Accedi ai tuoi dizionari di contenuto in tutta la tua applicazione:

      src/App.tsx
      import { createSignal, type Component } from "solid-js";
import solidLogo from "./assets/solid.svg";
import viteLogo from "/vite.svg";
import "./App.css";
import { IntlayerProvider, useIntlayer } from "solid-intlayer";

const AppContent: Component = () => {
  const [count, setCount] = createSignal(0);
  const content = useIntlayer("app");

  return (
    <>
      <div>
        <a href="https://vitejs.dev" target="_blank">
          <img src={viteLogo} class="logo" alt={content.viteLogo.value} />
        </a>
        <a href="https://www.solidjs.com/" target="_blank">
          <img
            src={solidLogo}
            class="logo solid"
            alt={content.solidLogo.value}
          />
        </a>
      </div>
      <h1>{content.title}</h1>
      <div class="card">
        <button onClick={() => setCount((count) => count + 1)}>
          {content.count({ count: count() })}
        </button>
        <p>{content.edit}</p>
      </div>
      <p class="read-the-docs">{content.readTheDocs}</p>
    </>
  );
};

const App: Component = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;
      In Solid, useIntlayer restituisce una funzione accessor (ad esempio, `content.). Devi chiamare questa funzione per accedere al contenuto reattivo.

      Se vuoi usare il tuo contenuto in un attributo string, come alt, title, href, aria-label, ecc., devi chiamare 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)}" />

    6. Cambiare la lingua del tuo contenuto

      Opzionale

      Per cambiare la lingua del tuo contenuto, puoi usare la funzione setLocale fornita dall'hook useLocale. Questa funzione ti permette di impostare la locale dell'applicazione e aggiornare il contenuto di conseguenza.

      src/components/LocaleSwitcher.tsx
      import { type Component, For } from "solid-js";
import { Locales } from "intlayer";
import { useLocale } from "solid-intlayer";

const LocaleSwitcher: Component = () => {
  const { locale, setLocale, availableLocales } = useLocale();

  return (
    <select
      value={locale()}
      onChange={(e) => setLocale(e.currentTarget.value as Locales)}
    >
      <For each={availableLocales}>
        {(loc) => (
          <option value={loc} selected={loc === locale()}>
            {loc}
          </option>
        )}
      </For>
    </select>
  );
};

    7. Aggiungere il routing localizzato alla tua applicazione

      Opzionale

      Lo scopo di questo passo è creare route uniche per ogni lingua. Questo è utile per SEO e URL SEO-friendly. Esempio:

      plaintext
      - https://example.com/about
- https://example.com/es/about
- https://example.com/fr/about

      Per aggiungere il routing localizzato alla tua applicazione, puoi usare @solidjs/router.

      Prima, installa le dipendenze necessarie:

      bash
      npm install @solidjs/router

      Poi, avvolgi la tua applicazione con il Router e definisci le tue route usando localeMap:

      src/index.tsx
      import { render } from "solid-js/web";
import { Router } from "@solidjs/router";
import App from "./App";

const root = document.getElementById("root");

render(
  () => (
    <Router>
      <App />
    </Router>
  ),
  root!
);
      src/App.tsx
      import { type Component } from "solid-js";
import { Route } from "@solidjs/router";
import { localeMap } from "intlayer";
import { IntlayerProvider } from "solid-intlayer";
import Home from "./pages/Home";
import About from "./pages/About";

const App: Component = () => (
  <IntlayerProvider>
    {localeMap(({ locale, urlPrefix }) => (
      <Route
        path={urlPrefix || "/"}
        component={(props: any) => (
          <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>
        )}
      >
        <Route path="/" component={Home} />
        <Route path="/about" component={About} />
      </Route>
    ))}
  </IntlayerProvider>
);

export default App;

    8. Cambiare l'URL quando la lingua cambia

      Opzionale

      Per cambiare l'URL quando la locale cambia, puoi usare la prop onLocaleChange fornita dall'hook useLocale. Puoi usare gli hook useNavigate e useLocation da @solidjs/router per aggiornare il percorso dell'URL.

      src/components/LocaleSwitcher.tsx
      import { type Component, For } from "solid-js";
import { useLocation, useNavigate } from "@solidjs/router";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "solid-intlayer";

const LocaleSwitcher: Component = () => {
  const location = useLocation();
  const navigate = useNavigate();
  const { locale, setLocale, availableLocales } = useLocale({
    onLocaleChange: (loc) => {
      const pathWithLocale = getLocalizedUrl(location.pathname, loc);
      navigate(pathWithLocale);
    },
  });

  return (
    <select
      value={locale()}
      onChange={(e) => setLocale(e.currentTarget.value as any)}
    >
      <For each={availableLocales}>
        {(loc) => (
          <option value={loc} selected={loc === locale()}>
            {loc}
          </option>
        )}
      </For>
    </select>
  );
};

    9. Cambiare gli attributi di lingua e direzione dell'HTML

      Opzionale

      Aggiorna gli attributi lang e dir del tag <html> per corrispondere alla locale corrente per accessibilità e SEO.

      src/App.tsx
      import { createEffect, type Component } from "solid-js";
import { useLocale } from "solid-intlayer";
import { getHTMLTextDir } from "intlayer";

const AppContent: Component = () => {
  const { locale } = useLocale();

  createEffect(() => {
    document.documentElement.lang = locale();
    document.documentElement.dir = getHTMLTextDir(locale());
  });

  return (
    // ... Il contenuto della tua applicazione
  );
};

    10. Creare un Componente Link Localizzato

      Opzionale

      Crea un componente Link personalizzato che prefissa automaticamente gli URL interni con la lingua corrente.

      src/components/Link.tsx
      import { type ParentComponent } from "solid-js";
import { A, type AnchorProps } from "@solidjs/router";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "solid-intlayer";

export const Link: ParentComponent<AnchorProps> = (props) => {
  const { locale } = useLocale();

  const isExternal = () => props.href.startsWith("http");
  const localizedHref = () =>
    isExternal() ? props.href : getLocalizedUrl(props.href, locale());

  return <A {...props} href={localizedHref()} />;
};

    11. Renderizzare Markdown

      Opzionale

      Intlayer supporta il rendering del contenuto Markdown direttamente nella tua applicazione Solid usando il suo parser interno. Per impostazione predefinita, Markdown è trattato come testo normale. Per renderizzarlo come HTML ricco, avvolgi la tua applicazione con il MarkdownProvider.

      Poi puoi usarlo nei tuoi componenti:

      tsx
      import { useIntlayer } from "solid-intlayer";

const MyComponent = () => {
  const content = useIntlayer("my-content");

  return (
    <div>
      {/* Renderizzato come HTML tramite MarkdownProvider */}
      {content.markdownContent}
    </div>
  );
};

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

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

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

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer. Questo consente di evitare di eseguirne il commit nel repository Git.

    Per fare questo, 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 Intlayer ufficiale per VS Code.

    Installa da VS Code Marketplace

    Approfondimenti

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

    Domande frequenti

    Vite non ha un'opinione sull'i18n, quindi la scelta viene dall'ecosistema Solid:

    • @solid-primitives/i18n: la primitiva della community, un dizionario piatto che assembli e carichi tu stesso.
    • i18next con un wrapper Solid: cataloghi maturi, ma nessuna storia di reattività propria.
    • Intlayer: contenuto dichiarato accanto a ogni componente e compilato dal plugin Vite in fase di build, completamente tipizzato, con traduzione AI, un editor visivo e un CMS.

    Il vantaggio specifico di Vite è che le traduzioni sono risolte e sottoposte a tree shaking in fase di compilazione invece di essere recuperate come JSON a runtime, così una pagina invia solo le voci che renderizza. Vedi perché Intlayer e il benchmark.

    Molto meno di una configurazione basata su namespace, perché una pagina non scarica mai un catalogo che non renderizza. Il compilatore in fase di build sostituisce le chiamate useIntlayer con le esatte voci del dizionario che un componente utilizza, quindi le chiavi e le lingue non utilizzate vengono eliminate, 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 11 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.
    Nuxt e VueSolid Start