Creation:2025-04-18Last update:2026-05-31

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

    ide.intlayer.org

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

    ide.intlayer.org

    Consulta il Template dell'Applicazione su GitHub.

    1. Installa le dipendenze

      Installa i pacchetti necessari usando npm:

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

      • intlayer

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

      • svelte-intlayer Il pacchetto che integra Intlayer con l'applicazione Svelte. Fornisce context provider e hook per l'internazionalizzazione in Svelte.

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

    2. Configurazione del tuo 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 localizzazioni    ],    defaultLocale: Locales.ENGLISH,  },};export default config;
      Attraverso questo file di configurazione, puoi impostare URL localizzati, reindirizzamenti 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 di configurazione.

    3. Integra Intlayer nella tua configurazione Vite

      Aggiungi il plugin intlayer nella tua configurazione.

      vite.config.ts
      import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [svelte(), intlayer()],});
      Il plugin Vite intlayer() viene utilizzato per integrare Intlayer con Vite. Garantisce la generazione 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: {
    title: t({
      en: "Hello World",
      fr: "Bonjour le monde",
      es: "Hola mundo",
    }),
  },
} satisfies Dictionary;

export default appContent;
      Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione non appena sono 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}).
      Per maggiori dettagli, consulta la documentazione sulla dichiarazione del contenuto.

    5. Utilizza Intlayer nel tuo codice

      src/App.svelte
      <script>  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("app");</script><div><!-- 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>
      Se la tua app esiste già, puoi utilizzare l' Intlayer Compiler in combinazione con il comando extract per convertire migliaia di componenti in un secondo.

    6. Cambia la lingua del tuo contenuto

      Opzionale
      src/App.svelte
      <script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from "svelte-intlayer";// Ottieni informazioni sulla locale e la funzione setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Gestisci il cambio di localeconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  setLocale(newLocale);};</script><div>  <select value={$locale} on:change={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

    7. Renderizza Markdown

      Opzionale

      Intlayer supporta il rendering di contenuti Markdown direttamente nella tua applicazione Svelte. Per default, il Markdown è trattato come testo semplice. Per convertire il Markdown in HTML ricco, puoi integrare @humanspeak/svelte-markdown o un altro parser Markdown.

      Per vedere come dichiarare contenuti markdown usando il pacchetto intlayer, consulta la documentazione markdown.
      src/App.svelte
      <script>  import { setIntlayerMarkdown } from "svelte-intlayer";  setIntlayerMarkdown((markdown) =>   // rendi il contenuto markdown come stringa   return markdown;  );</script><h1>{$content.markdownContent}</h1>
      Puoi anche accedere ai dati del front-matter del tuo markdown usando la proprietà content.markdownContent.metadata.xxx.

    8. Configura l'editor / CMS di intlayer

      Opzionale

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

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

    9. Aggiungi il routing localizzato alla tua applicazione

      Opzionale

      Per gestire il routing localizzato nella tua applicazione Svelte, puoi usare svelte-spa-router insieme a localeFlatMap di Intlayer per generare le rotte per ogni locale.

      Per prima cosa, installa svelte-spa-router:

      bash
      npm install svelte-spa-routernpx intlayer init

      Quindi, crea un file Router.svelte per definire le tue rotte:

      src/Router.svelte
      <script lang="ts">import { localeFlatMap } from "intlayer";import Router from "svelte-spa-router";import { wrap } from "svelte-spa-router/wrap";import App from "./App.svelte";const routes = Object.fromEntries(    localeFlatMap(({locale, urlPrefix}) => [    [        urlPrefix || '/',        wrap({            component: App as any,            props: {                locale,            },        }),    ],    ]));</script><Router {routes} />

      Aggiorna il tuo main.ts per montare il componente Router invece di App:

      src/main.ts
      import { mount } from "svelte";import Router from "./Router.svelte";const app = mount(Router, {  target: document.getElementById("app")!,});export default app;

      Infine, aggiorna il tuo App.svelte per ricevere la prop locale e utilizzarla con useIntlayer:

      src/App.svelte
      <script lang="ts">import type { Locale } from 'intlayer';import { useIntlayer } from "svelte-intlayer";import Counter from './lib/Counter.svelte';import LocaleSwitcher from './lib/LocaleSwitcher.svelte';export let locale: Locale;// Usa useIntlayer per ottenere i contenuti localizzati per l'app$: content = useIntlayer('app', locale);</script><main>  <div class="locale-switcher-container">    <LocaleSwitcher currentLocale={locale} />  </div>  <!-- ... resto della tua app ... --></main>

      Configura il Routing lato Server (Opzionale)

      In parallelo, puoi anche utilizzare intlayerProxy per aggiungere il routing lato server alla tua applicazione. Questo plugin rileverà automaticamente la locale corrente basandosi sull'URL e imposterà il cookie della locale appropriata. Se non viene specificata alcuna locale, il plugin determinerà la locale più appropriata basandosi sulle preferenze linguistiche del browser dell'utente. Se non viene rilevata alcuna locale, effettuerà un reindirizzamento alla locale predefinita.

      Nota che per utilizzare intlayerProxy in produzione, è necessario spostare il pacchetto vite-intlayer da devDependencies a dependencies.
      vite.config.ts
      import { defineConfig } from "vite";
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { intlayer, intlayerProxy } from "vite-intlayer";

  plugins: [intlayerProxy(), // should be placed first
 svelte(), intlayer()],
});

    10. Cambiare l'URL quando la lingua cambia

      Opzionale

      Per permettere agli utenti di cambiare lingua e aggiornare di conseguenza l'URL, puoi creare un componente LocaleSwitcher. Questo componente utilizzerà getLocalizedUrl da intlayer e push da svelte-spa-router.

      src/lib/LocaleSwitcher.svelte
      <script lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";import { push } from "svelte-spa-router";export let currentLocale: string | undefined = undefined;// Ottieni le informazioni sulla linguaconst { locale, availableLocales } = useLocale();// Gestisci il cambio di linguaconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  const currentUrl = window.location.pathname;  const url = getLocalizedUrl( currentUrl, newLocale);  push(url);};</script><div class="locale-switcher">  <select value={currentLocale ?? $locale} onchange={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

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

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer. Questo permette di evitare di committarli nel tuo repository Git.

    Per farlo, puoi aggiungere le seguenti istruzioni nel 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 la Intlayer VS Code Extension ufficiale.

    Installa dal VS Code Marketplace

    Questa estensione offre:

    • Completamento automatico per le chiavi di traduzione.
    • Rilevamento errori in tempo reale per traduzioni mancanti.
    • Anteprime inline dei contenuti tradotti.
    • Azioni rapide per creare e aggiornare facilmente le traduzioni.

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

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

    Vai oltre

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

    Vite e Solid
    SvelteKit