Autore:
    Aymeric PINEAU
    Creazione:2025-11-20Ultimo aggiornamento:2026-08-30

    Traduci il tuo sito SvelteKit usando Intlayer | Internazionalizzazione (i18n)

    ide.intlayer.org
    intlayer-sveltekit-template.vercel.app

    Indice

    Perché Intlayer rispetto alle alternative?

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

    Intlayer è ottimizzato per funzionare perfettamente con SvelteKit offrendo routing multilingue, supporto SSR 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 SvelteKit

    Vedi Application Template su GitHub.

    Per iniziare, crea un nuovo progetto SvelteKit. Ecco la struttura finale che realizzeremo:

    bash
    .
├── intlayer.config.ts
├── package.json
├── src
│   ├── app.d.ts
│   ├── app.html
│   ├── hooks.server.ts
│   ├── lib
│   │   ├── getLocale.ts
│   │   ├── LocaleSwitcher.svelte
│   │   └── LocalizedLink.svelte
│   ├── params
│   │   └── locale.ts
│   └── routes
│       ├── [[locale=locale]]
│       │   ├── +layout.svelte
│       │   ├── +layout.ts
│       │   ├── +page.svelte
│       │   ├── +page.ts
│       │   ├── about
│       │   │   ├── +page.svelte
│       │   │   ├── +page.ts
│       │   │   └── page.content.ts
│       │   ├── Counter.content.ts
│       │   ├── Counter.svelte
│       │   ├── Header.content.ts
│       │   ├── Header.svelte
│       │   ├── home.content.ts
│       │   └── layout.content.ts
│       ├── +layout.svelte
│       └── layout.css
├── static
│   ├── favicon.svg
│   └── robots.txt
├── svelte.config.js
├── tsconfig.json
└── vite.config.ts

    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 svelte-intlayer
npm install vite-intlayer --save-dev
      • intlayer: Il pacchetto core per l'internazionalizzazione (i18n).
      • svelte-intlayer: Fornisce context provider e store per Svelte/SvelteKit.
      • vite-intlayer: Il plugin Vite per integrare le dichiarazioni di contenuto nel processo di build.

    2. Configurazione del tuo progetto

      Crea un file di configurazione nella root del tuo progetto:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

    3. Integrare Intlayer nella Configurazione di Vite

      Aggiorna il tuo vite.config.ts per includere il plugin Intlayer. Questo plugin gestisce la transpilation dei tuoi file di contenuto.

      vite.config.ts
      import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer(), sveltekit()], // l'ordine è importante, Intlayer deve essere posizionato prima di SvelteKit
});

    4. Dichiarare il Tuo Contenuto

      Crea i tuoi file di dichiarazione del contenuto in qualsiasi punto della cartella src (ad esempio, src/lib/content o accanto ai tuoi componenti). Questi file definiscono il contenuto traducibile per la tua applicazione utilizzando la funzione t() per ogni locale.

    5. Utilizzare Intlayer nei Tuoi Componenti

      Ora puoi utilizzare la funzione useIntlayer in qualsiasi componente Svelte. Restituisce un reactive store che si aggiorna automaticamente quando la locale cambia. La funzione rispetterà automaticamente la locale corrente (sia durante SSR che durante la navigazione lato client).

      per accedere al suo valore reattivo (ad esempio, $content.title).

      src/lib/components/Component.svelte
      <script lang="ts">
  import { useIntlayer } from "svelte-intlayer";

  // "hero-section" corrisponde alla chiave definita nel Passo 4
  const content = useIntlayer("hero-section");
</script>

<!-- Renderizza il contenuto come contenuto semplice  -->
<h1>{$content.title}</h1>
<!-- Per rendere il contenuto modificabile usando l'editor -->
<h1>{@const Title = $content.title}<Title /></h1>
<!-- Per rendere il contenuto come stringa -->
<div aria-label={$content.title.value}></div>
<div aria-label={$content.title.toString()}></div>
<div aria-label={String($content.title)}></div>

    6. Configurare il routing

      Opzionale

      I passaggi seguenti mostrano come configurare il routing basato sulla locale in SvelteKit. Questo permette agli URL di includere il prefisso della locale (es. /en/about, /fr/about) per migliorare la SEO e l'esperienza utente.

      bash
      .
└─── src
    ├── app.d.ts                  # Definisce il tipo di locale
    ├── hooks.server.ts           # Gestisce il routing della locale
    ├── lib
    │   └── getLocale.ts          # Controlla la locale dall'header, cookie
    ├── params
    │   └── locale.ts             # Definisce il parametro locale
    └── routes
        ├── [[locale=locale]]     # Raggruppa in un gruppo di route per impostare la locale
        │   ├── +layout.svelte    # Layout locale per la route
        │   ├── +layout.ts
        │   ├── +page.svelte
        │   ├── +page.ts
        │   └── about
        │       ├── +page.svelte
        │       └── +page.ts
        └── +layout.svelte         # Layout radice per i font e gli stili globali

    7. Gestire il Rilevamento della Locale lato Server

      In SvelteKit, il server deve conoscere la locale dell'utente per renderizzare il contenuto corretto durante il SSR. Usiamo hooks.server.ts per rilevare la locale dall'URL o dai cookie.

      Crea o modifica src/hooks.server.ts:

      src/hooks.server.ts
      import type { Handle } from "@sveltejs/kit";
import { getLocalizedUrl } from "intlayer";
import { getLocale } from "$lib/getLocale";

export const handle: Handle = async ({ event, resolve }) => {
  const detectedLocale = getLocale(event);

  // Controlla se il percorso corrente inizia già con una locale (es. /fr, /en)
  const pathname = event.url.pathname;
  const targetPathname = getLocalizedUrl(pathname, detectedLocale);

  // Se NON è presente una locale nell'URL (es. l'utente visita "/"), reindirizzalo
  if (targetPathname !== pathname) {
    return new Response(undefined, {
      headers: { Location: targetPathname },
      status: 307, // Reindirizzamento temporaneo
    });
  }

  return resolve(event, {
    transformPageChunk: ({ html }) => html.replace("%lang%", detectedLocale),
  });
};

      Quindi, crea un helper per ottenere la locale dell'utente dall'evento della richiesta:

      src/lib/getLocale.ts
      import {
  configuration,
  getLocaleFromStorage,
  localeDetector,
  type Locale,
} from "intlayer";
import type { RequestEvent } from "@sveltejs/kit";

/**
 * Ottieni la locale dell'utente dall'evento di richiesta.
 * Questa funzione è utilizzata nel hook `handle` in `src/hooks.server.ts`.
 *
 * Prima tenta di ottenere la locale dallo storage di Intlayer (cookie o header personalizzati).
 * Se la locale non viene trovata, ricorre alla negoziazione "Accept-Language" del browser.
 *
 * @param event - L'evento di richiesta da SvelteKit
 * @returns La locale dell'utente
 */
export const getLocale = (event: RequestEvent): Locale => {
  const defaultLocale = configuration?.internationalization?.defaultLocale;

  // Prova a ottenere la locale dallo storage di Intlayer (cookie o header)
  const storedLocale = getLocaleFromStorage({
    // Accesso ai cookie di SvelteKit
    getCookie: (name: string) => event.cookies.get(name) ?? null,
    // Accesso alle intestazioni di SvelteKit
    getHeader: (name: string) => event.request.headers.get(name) ?? null,
  });

  if (storedLocale) {
    return storedLocale;
  }

  // Ripiego sulla negoziazione "Accept-Language" del browser
  const negotiatorHeaders: Record<string, string> = {};

  // Conversione dell'oggetto Headers di SvelteKit in un semplice Record<string, string>
  event.request.headers.forEach((value, key) => {
    negotiatorHeaders[key] = value;
  });

  // Controlla la locale dall'intestazione `Accept-Language`
  const userFallbackLocale = localeDetector(negotiatorHeaders);

  if (userFallbackLocale) {
    return userFallbackLocale;
  }

  // Restituisce la locale di default se non viene trovata una corrispondenza
  return defaultLocale;
};
      getLocaleFromStorage controllerà la locale dall'header o dal cookie a seconda della tua configurazione. Vedi Configurazione per maggiori dettagli.
      La funzione localeDetector gestirà l'header Accept-Language e restituirà la corrispondenza migliore.

      Se la locale non è configurata, vogliamo restituire un errore 404. Per semplificare, possiamo creare una funzione match per verificare se la locale è valida:

      /src/params/locale.ts
      export const match = (param: Locale = defaultLocale): boolean =>
  locales.includes(param);

      Nota: Assicurati che il tuo file src/app.d.ts includa la definizione della locale:

      typescript
      declare global {
  namespace App {
    interface Locals {
      locale: import("intlayer").Locale;
    }
  }
}

      Per il file +layout.svelte, possiamo rimuovere tutto, mantenendo solo contenuti statici, non correlati a i18n:

      src/+layout.svelte
      <script lang="ts">
     import './layout.css';

    let { children } = $props();
</script>

<div class="app">
    {@render children()}
</div>

<style>
    .app {
    /*  */
    }
</style>

      Successivamente, crea una nuova pagina e layout sotto il gruppo [[locale=locale]]:

      src/routes/[[locale=locale]]/+layout.ts
      import type { Load } from "@sveltejs/kit";
import { defaultLocale, type Locale } from "intlayer";

export const prerender = true;

// Usa il tipo generico Load
export const load: Load = ({ params }) => {
  const locale: Locale = (params.locale as Locale) ?? defaultLocale;

  return {
    locale,
  };
};
      src/routes/[[locale=locale]]/+layout.svelte
      <script lang="ts">
    import type { Snippet } from 'svelte';
    import { useIntlayer, setupIntlayer } from "svelte-intlayer";
    import Header from './Header.svelte';
    import type { LayoutData } from './$types';

    let { children, data }: { children: Snippet, data: LayoutData } = $props();

    // Inizializza Intlayer con la locale dalla route
  $effect(() => {
      setupIntlayer(data.locale);
  });
    // Usa il dizionario dei contenuti del layout
    const layoutContent = useIntlayer('layout');
</script>

<Header />

<main>
    {@render children()}
</main>

<footer>
    <p>
        {$layoutContent.footer.prefix.value}{' '}
        <a href="https://svelte.dev/docs/kit">{$layoutContent.footer.linkLabel.value}</a>{' '}
        {$layoutContent.footer.suffix.value}
    </p>
</footer>

<style>
  /*  */
</style>
      src/routes/[[locale=locale]]/+page.ts
      export const prerender = true;
      src/routes/[[locale=locale]]/+page.svelte
      <script lang="ts">
    import { useIntlayer } from "svelte-intlayer";

    // Usa il dizionario dei contenuti della home
    const homeContent = useIntlayer('home');
</script>

<svelte:head>
    <title>{$homeContent.title.value}</title>
</svelte:head>

<section>
    <h1>
        {$homeContent.title}
    </h1>
</section>

<style>
  /*  */
</style>

    8. Link Internazionalizzati

      Opzionale

      Per la SEO, si consiglia di anteporre alle tue rotte la locale (ad esempio, /en/about, /fr/about). Questo componente antepone automaticamente qualsiasi link con la locale corrente.

      src/lib/components/LocalizedLink.svelte
      <script lang="ts">
  import { getLocalizedUrl } from "intlayer";
  import { useLocale } from "svelte-intlayer";

  let { href = "" } = $props();
  const { locale } = useLocale();

  // Helper per anteporre l'URL con la locale corrente
  $: localizedHref = getLocalizedUrl(href, $locale);
</script>

<a href={localizedHref}>
  <slot />
</a>

      Se usi goto di SvelteKit, puoi usare la stessa logica con getLocalizedUrl per navigare all'URL localizzato:

      typescript
      import { goto } from "$app/navigation";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "svelte-intlayer";

const { locale } = useLocale();
const localizedPath = getLocalizedUrl("/about", $locale);
goto(localizedPath); // Naviga verso /en/about o /fr/about a seconda della locale

    9. Selettore di Lingua

      Opzionale

      Per permettere agli utenti di cambiare lingua, aggiorna l'URL.

      src/lib/components/LanguageSwitcher.svelte
      <script lang="ts">
  import { getLocalizedUrl, getLocaleName } from 'intlayer';
  import { useLocale } from "svelte-intlayer";
  import { page } from '$app/stores';
  import { goto } from '$app/navigation';

  const { locale, setLocale, availableLocales } = useLocale({
    onLocaleChange: (newLocale) => {
      const localizedPath = getLocalizedUrl($page.url.pathname, newLocale);
      goto(localizedPath);
    },
  });
</script>

<ul class="locale-list">
  {#each availableLocales as localeEl}
    <li>
      <a
        href={getLocalizedUrl($page.url.pathname, localeEl)}
        onclick={(e) => {
          e.preventDefault();
          setLocale(localeEl); // Imposterà la locale nello store e attiverà onLocaleChange
        }}
        class:active={$locale === localeEl}
      >
        {getLocaleName(localeEl)}
      </a>
    </li>
  {/each}
</ul>

<style>
  /* */
</style>

    10. Aggiungere un proxy backend

      Opzionale

      Per aggiungere un proxy backend alla tua applicazione SvelteKit, puoi usare la funzione intlayerProxy fornita dal plugin vite-intlayer. Questo plugin rileverà automaticamente la migliore locale per l'utente basandosi sull'URL, i cookie e le preferenze della lingua del browser.

      A partire da Intlayer v9, intlayerProxy() è integrato direttamente nel plugin intlayer() e abilitato di default attraverso l'opzione routing.enableProxy (true di default). Registrarlo separatamente come mostrato di seguito è ora opzionale — viene mantenuto per compatibilità con versioni precedenti e per setup che necessitano di controllare l'ordine dei plugin. Imposta routing.enableProxy: false per disabilitarlo. Vedi le note di rilascio v9.
      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";
import { sveltekit } from "@sveltejs/kit/vite";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    sveltekit(),
  ],],
});

    11. Configurare l'editor / CMS di intlayer

      Opzionale

      Per configurare l'editor di intlayer, devi seguire la documentazione dell'editor di intlayer.

      Per configurare il CMS di intlayer, devi seguire la documentazione del CMS di intlayer.

      Per poter visualizzare il selettore dell'editor intlayer, dovrai utilizzare la sintassi del componente nel tuo contenuto intlayer.

      Component.svelte
      <script lang="ts">
  import { useIntlayer } from "svelte-intlayer";

  const content = useIntlayer("component");
</script>

<div>

  <!-- Renderizza il contenuto come contenuto semplice -->
  <h1>{$content.title}</h1>

  <!-- Renderizza il contenuto come componente (richiesto dall'editor) -->
  {@const Component = $content.component}<Component />
</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

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer.

    .gitignore
    # Ignora i file generati da Intlayer
.intlayer

    Vai oltre

    Domande frequenti

    • svelte-i18n e typesafe-i18n: cataloghi di messaggi basati su store, collegati alle funzioni load a mano.
    • Paraglide: messaggi compilati con una forte storia di tipizzazione, focalizzato solo sul livello di messaggi.
    • Intlayer: contenuto dichiarato accanto a ogni componente e compilato in fase di build, con routing consapevole delle locale, rilevamento della locale lato server, traduzione AI, un editor visivo e un CMS.

    Su SvelteKit la differenza si vede nei pezzi lato server: il rilevamento della locale negli hook, i link localizzati e l'integrazione dell'editor vengono con la libreria invece di essere assemblati per progetto. Vedi perché Intlayer e il benchmark i18n di Svelte.

    Molto meno di una configurazione basata su namespace, perché una pagina non scarica mai un catalogo che non renderizza. Il markup renderizzato lato server risolve i suoi contenuti sul server, e 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 Svelte I18n 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 12 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.
    Vite e SvelteVite e Preact