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

    Traduci il tuo sito Angular 22 (Vite) utilizzando Intlayer | Internazionalizzazione (i18n)

    Sommario

    Perché Intlayer rispetto alle alternative?

    Rispetto alle soluzioni principali come ngx-translate o angular-l10n, Intlayer è una soluzione dotata di ottimizzazioni integrate come:

    Intlayer è ottimizzato per funzionare perfettamente con Angular offrendo ambito del contenuto a livello di componente, traduzioni caricate lazy 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 Angular

    ide.intlayer.org
    intlayer-angular-22-template.vercel.app

    Vedi il Modello di Applicazione su GitHub.

    1. Installare le dipendenze

      Installa i pacchetti necessari utilizzando 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 angular-intlayer
npm install @angular-builders/custom-esbuild --save-dev

      • intlayer

        Il pacchetto base che fornisce gli strumenti di internazionalizzazione per la gestione della configurazione, traduzione, dichiarazione dei contenuti, transpilazione e comandi CLI.

      • angular-intlayer Il pacchetto che integra Intlayer con l'applicazione Angular. Fornisce fornitori di contesto e hook per l'internazionalizzazione Angular.

      • @angular-builders/custom-esbuild Necessario per personalizzare la configurazione esbuild della CLI di Angular.

    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 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 tua Configurazione Angular

      Per integrare Intlayer con la CLI di Angular, devi utilizzare un costruttore (builder) personalizzato. Questa guida presuppone che tu stia utilizzando Vite/esbuild (predefinito per i progetti Angular 22).

      Per prima cosa, modifica il tuo angular.json per utilizzare il costruttore esbuild personalizzato. Aggiorna le configurazioni build e serve:

      angular.json
      {
  "projects": {
    "your-app-name": {
      "architect": {
        "build": {
          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"
          "options": {
            "define": {
              "process.env": "{}",
            },
            "plugins": ["./esbuild.plugins.ts"],
            "browser": "src/main.ts",
            // ...
          },
        },
        "serve": {
          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"
          "options": {
            "prebundle": {
              "exclude": [
                "intlayer",
                "angular-intlayer",
                "@intlayer/config/built",
                "@intlayer/core"
              ]
          },
        },
      },
    },
  },
}
      Assicurati di sostituire your-app-name con il nome effettivo del tuo progetto in angular.json.

      Successivamente, crea un file esbuild.plugins.ts nella directory radice del tuo progetto:

      esbuild.plugins.ts
      import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";

export default [intlayerEsbuildPlugin()];
      La funzione intlayerEsbuildPlugin configura esbuild con Intlayer. Inietta il plugin per gestire i file di dichiarazione dei contenuti e imposta le configurazioni per prestazioni ottimali.

      Utenti NX: I builder Angular di NX caricano i file dei plugin tramite la risoluzione ESM nativa di Node e non compilano i file dei plugin TypeScript al volo. Utilizza invece un file .mjs e aggiorna di conseguenza il riferimento plugins in angular.json:

      esbuild.plugins.mjs
      import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";

export default [intlayerEsbuildPlugin()];

      Quindi in angular.json punta a "./esbuild.plugins.mjs" invece di "./esbuild.plugins.ts".

    4. Dichiara i tuoi Contenuti

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

      Le tue dichiarazioni di contenuto possono essere definite in qualsiasi punto della tua applicazione purché siano incluse nella directory contentDir (per impostazione predefinita, ./src). E corrispondano all'estensione del file della dichiarazione di 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.

    5. Utilizza Intlayer nel tuo Codice

      Per utilizzare le funzionalità di internazionalizzazione di Intlayer in tutta l'applicazione Angular, è necessario fornire Intlayer nella configurazione dell'applicazione.

      src/app/app.config.ts
      import { ApplicationConfig } from "@angular/core";
import { provideRouter } from "@angular/router";
import { provideIntlayer } from "angular-intlayer";
import { routes } from "./app.routes";

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideIntlayer(), // Aggiungi qui il provider Intlayer
  ],
};

      Quindi, puoi utilizzare la funzione useIntlayer all'interno di qualsiasi componente.

      src/app/app.component.ts
      import { Component } from "@angular/core";
import { RouterOutlet } from "@angular/router";
import { useIntlayer } from "angular-intlayer";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: "./app.component.html",
  styleUrl: "./app.component.css",
})
export class AppComponent {
  content = useIntlayer("app");
}

      E nel tuo template:

      src/app/app.component.html
      <div class="content">
  <h1>{{ content().title }}</h1>
  <p>{{ content().congratulations }}</p>
</div>

      Il contenuto Intlayer viene restituito come un Signal, quindi accedi ai valori chiamando il segnale: content().title.

    6. Cambia la lingua dei tuoi contenuti

      Opzionale

      Per cambiare la lingua dei tuoi contenuti, puoi utilizzare la funzione setLocale fornita dalla funzione useLocale. Questo ti consente di impostare la lingua dell'applicazione e aggiornare il contenuto di conseguenza.

      Crea un componente per passare da una lingua all'altra:

      src/app/locale-switcher.component.ts
      import { Component } from "@angular/core";
import { CommonModule } from "@angular/common";
import { useLocale } from "angular-intlayer";

@Component({
  selector: "app-locale-switcher",
  standalone: true,
  imports: [CommonModule],
  template: `
    <div class="locale-switcher">
      <select
        [value]="locale()"
        (change)="setLocale($any($event.target).value)"
      >
        @for (loc of availableLocales; track loc) {
          <option [value]="loc">{{ loc }}</option>
        }
      </select>
    </div>
  `,
})
export class LocaleSwitcherComponent {
  localeCtx = useLocale();

  locale = this.localeCtx.locale;
  availableLocales = this.localeCtx.availableLocales;
  setLocale = this.localeCtx.setLocale;
}

      Quindi, utilizza questo componente nel tuo app.component.ts:

      src/app/app.component.ts
      import { Component } from "@angular/core";
import { RouterOutlet } from "@angular/router";
import { useIntlayer } from "angular-intlayer";
import { LocaleSwitcherComponent } from "./locale-switcher.component";

@Component({
  selector: "app-root",
  standalone: true,
  imports: [RouterOutlet, LocaleSwitcherComponent],
  templateUrl: "./app.component.html",
  styleUrl: "./app.component.css",
})
export class AppComponent {
  content = useIntlayer("app");
}

    Configurare TypeScript

    Intlayer utilizza l'aumento dei moduli per ottenere i vantaggi di TypeScript e rendere la base di codice più solida.

    Autocompletamento

    Errore di traduzione

    Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

    tsconfig.json
    {
  // ... Le tue configurazioni TypeScript esistenti
  "include": [
    // ... Le tue configurazioni TypeScript esistenti
    ".intlayer/**/*.ts", // Includi i tipi autogenerati
  ],
}

    Configurazione Git

    Si consiglia di ignorare i file generati da Intlayer. Ciò ti consente di evitare di inserirli nel tuo 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 Marketplace VS Code

    Questa estensione fornisce:

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

    Per ulteriori dettagli su come utilizzare l'estensione, consulta la documentazione dell'Estensione VS Code di Intlayer.

    Vai oltre

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

    Domande frequenti

    • @angular/localize, l'i18n integrato: i messaggi sono estratti in XLIFF e ogni locale è compilato nella propria build, il che significa un artefatto di deployment per lingua e nessun cambio di locale a runtime.
    • ngx-translate e Transloco: cataloghi JSON a runtime caricati attraverso un servizio, con cambio di locale ma senza tipizzazione in fase di build.
    • Intlayer: contenuto dichiarato accanto a ogni componente e compilato in fase di build, completamente tipizzato, con cambio di locale a runtime, traduzione AI, un editor visivo e un CMS.

    Il motivo abituale per lasciare @angular/localize è il modello di una build per locale. Intlayer mantiene una singola build e cambia lingua a runtime. Vedi perché Intlayer.

    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 ngx-translate o la guida alla migrazione da Transloco 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 template 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 file sorgente, 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. Vedi il comando extract.

    Per una pipeline completamente automatizzata, il Compilatore Intlayer fa lo stesso in fase di build sul codice sorgente JSX, TSX, Vue e Svelte, generando i dizionari ad ogni modifica così non ci sono chiavi da mantenere a mano. Funziona per analisi statica, quindi le stringhe che esistono solo a runtime restano fuori portata, e ha bisogno di alcune annotazioni per distinguere il testo visibile all'utente dalla logica applicativa.

    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 LitAngular 19 (Webpack)