Ricevi notifiche sui prossimi lanci di Intlayer
    Creazione:2025-04-18Ultimo aggiornamento:2025-06-29

    Iniziare con l'internazionalizzazione (i18n) in Angular usando Intlayer

    Questo pacchetto è in fase di sviluppo. Consulta la issue per maggiori informazioni. Mostra il tuo interesse per Intlayer per Angular mettendo un like alla issue

    Cos'è Intlayer?

    Intlayer è una libreria innovativa e open-source per l'internazionalizzazione (i18n) progettata per semplificare il supporto multilingue nelle moderne applicazioni web.

    Con Intlayer, puoi:

    • Gestire facilmente le traduzioni utilizzando dizionari dichiarativi a livello di componente.
    • Localizzare dinamicamente i metadata, le rotte e i contenuti.
    • Garantire il supporto a TypeScript con tipi autogenerati, migliorando l'autocompletamento e il rilevamento degli errori.
    • Beneficiare di funzionalità avanzate, come il rilevamento e il cambio dinamico della lingua.

    Guida passo-passo per configurare Intlayer in un'applicazione Angular

    Passo 1: Installa le dipendenze

    Installa i pacchetti necessari usando npm:

    bash
    npm install intlayer angular-intlayer @intlayer/webpack
    • 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.

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

    • @intlayer/webpack Il pacchetto che integra Intlayer con Webpack. Viene utilizzato dall'Angular CLI per costruire i file di dichiarazione dei contenuti e monitorarli in modalità sviluppo.

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

    Il pacchetto che integra Intlayer con Webpack. Viene utilizzato dall'Angular CLI per costruire i file di dichiarazione dei contenuti e monitorarli in modalità sviluppo.

    Passo 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 sulla configurazione.

    Passo 3: Integra Intlayer nella configurazione di Angular

    Per integrare Intlayer con l'Angular CLI, hai due opzioni a seconda del builder: esbuild o webpack.

    Opzione 1: Usare esbuild (Consigliato)

    Per prima cosa, modifica il tuo angular.json per usare il builder esbuild personalizzato. Aggiorna la configurazione build:

    angular.json
    {  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application",          "options": {            "plugins": ["./esbuild/intlayer-plugin.ts"]          }        }      }    }  }}

    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 sulla configurazione.

    Passo 3: Integra Intlayer nella tua configurazione Angular

    Per integrare Intlayer con l’Angular CLI, hai due opzioni a seconda del builder: esbuild o webpack.

    Opzione 1: Usare esbuild (Consigliato)

    Per prima cosa, modifica il tuo angular.json per usare il builder personalizzato esbuild. Aggiorna la configurazione build:

    angular.json
    {  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application",          "options": {            "plugins": ["./esbuild/intlayer-plugin.ts"]          }        }      }    }  }}

    Assicurati di sostituire your-app-name con il nome effettivo del tuo progetto in angular.json.

    Successivamente, crea un file esbuild/intlayer-plugin.ts nella radice del tuo progetto:

    esbuild/intlayer-plugin.ts
    import { prepareIntlayer, watch } from "@intlayer/chokidar";import { getConfiguration, logger } from "@intlayer/config";import type { Plugin } from "esbuild";const intlayerPlugin: Plugin = {  name: "intlayer-esbuild-plugin",  setup(build) {    const configuration = getConfiguration();    let isWatching = false;    build.onStart(async () => {      logger("Plugin Intlayer esbuild avviato", {        level: "info",      });      if (build.initialOptions.watch && !isWatching) {        logger("Modalità watch abilitata. Avvio del watcher...", {          level: "info",        });        watch(configuration);        isWatching = true;      }      try {        await prepareIntlayer(configuration);      } catch (error) {        logger(`Errore nel plugin Intlayer esbuild: ${error}`, {          level: "error",        });      }    });  },};export default intlayerPlugin;

    Il intlayerPlugin per esbuild garantisce che Intlayer sia preparato prima dell'inizio della build e monitora le modifiche in modalità sviluppo.

    Opzione 2: Utilizzo di Webpack

    Per prima cosa, modifica il file angular.json per utilizzare il builder Webpack personalizzato. Aggiorna le configurazioni build e serve:

    angular.json
    {  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-webpack:browser",          "options": {            "customWebpackConfig": {              "path": "./webpack.config.js"            }          }        },        "serve": {          "builder": "@angular-builders/custom-webpack:dev-server"        }      }    }  }}

    Assicurati di sostituire your-app-name con il nome effettivo del tuo progetto in angular.json.

    Successivamente, crea un file webpack.config.js nella radice del tuo progetto:

    webpack.config.js
    const { IntlayerWebpackPlugin } = require("@intlayer/webpack");module.exports = {  plugins: [new IntlayerWebpackPlugin()],};

    Il IntlayerWebpackPlugin viene utilizzato per integrare Intlayer con Webpack. Garantisce la creazione dei file di dichiarazione dei contenuti e li monitora in modalità sviluppo. Definisce le variabili d'ambiente di Intlayer all'interno dell'applicazione. Inoltre, fornisce alias per ottimizzare le prestazioni.

    Passo 4: Dichiara il Tuo Contenuto

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

    src/app/app.content.ts
    import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    title: t({      en: "Hello",      fr: "Bonjour",      es: "Hola",    }),    congratulations: t({      it: "Congratulazioni! La tua app è in esecuzione.",      en: "Congratulations! Your app is running.",      fr: "Félicitations! Votre application est en cours d'exécution.",      es: "¡Felicidades! Tu aplicación está en ejecución.",    }),    exploreDocs: t({      it: "Esplora la Documentazione",      en: "Explore the Docs",      fr: "Explorer les Docs",      es: "Explorar los Docs",    }),    learnWithTutorials: t({      it: "Impara con i Tutorial",      en: "Learn with Tutorials",      fr: "Apprendre avec les Tutoriels",      es: "Aprender con los Tutorios",    }),    cliDocs: "CLI Docs",    angularLanguageService: t({      it: "Servizio Linguaggio Angular",      en: "Angular Language Service",      fr: "Service de Langage Angular",      es: "Servicio de Lenguaje Angular",    }),    angularDevTools: "Angular DevTools",    github: "Github",    twitter: "Twitter",    youtube: "Youtube",  },} 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,mjx,cjs,cjx}).

    Per maggiori dettagli, consulta la documentazione sulle dichiarazioni di contenuto.

    Passo 5: Utilizza Intlayer nel tuo codice

    Per utilizzare le funzionalità di internazionalizzazione di Intlayer in tutta la tua applicazione Angular, devi usare la funzione useIntlayer all'interno di un componente. Questa funzione, disponibile da angular-intlayer, fornisce l'accesso alle tue traduzioni come segnali reattivi. IntlayerProvider è registrato nella radice dell'applicazione, quindi non è necessario aggiungerlo ai provider del modulo.

    Accedi ai tuoi dizionari di contenuti nella classe del componente:

    src/app/hello-world.component.ts
    import { Component, signal } from "@angular/core";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-hello-world",  standalone: true,  template: `    <h1>{{ content().title }}</h1>    <div class="card">      <button type="button" (click)="increment()">        {{ content().count }} {{ count() }}      </button>      <p [innerHTML]="content().edit"></p>    </div>    <p class="read-the-docs">{{ content().readTheDocs }}</p>  `,})export class HelloWorldComponent {  content = useIntlayer("helloworld");  count = signal(0);  increment() {    this.count.update((value) => value + 1);  }}

    Il contenuto di Intlayer viene restituito come un Signal, quindi accedi ai valori chiamando il signal nel tuo template: content().title.

    (Opzionale) Passo 6: Cambiare la lingua del tuo contenuto

    Per cambiare la lingua del tuo contenuto, puoi usare la funzione setLocale fornita dalla funzione useLocale. Questo ti permette di impostare la localizzazione dell'applicazione e aggiornare il contenuto di conseguenza.

    Crea un componente per cambiare lingua:

    src/app/components/locale-switcher.component.ts
    import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { getLocaleName } from "intlayer";import { useLocale } from "angular-intlayer";import { FormsModule } from "@angular/forms";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule, FormsModule],  template: `    <div class="locale-switcher">      <select [ngModel]="locale()" (ngModelChange)="changeLocale($event)">        <option *ngFor="let loc of availableLocales" [value]="loc">          {{ getLocaleName(loc) }}        </option>      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeInfo = useLocale();  locale = this.localeInfo.locale;  availableLocales = this.localeInfo.availableLocales;  // Espone getLocaleName al template  getLocaleName = getLocaleName;  changeLocale(newLocale: string) {    this.localeInfo.setLocale(newLocale);  }}

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

    src/app/app.component.ts
    import { Component } from "@angular/core";import { HelloWorldComponent } from "./hello-world.component";import { LocaleSwitcherComponent } from "./components/locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [HelloWorldComponent, LocaleSwitcherComponent],  template: `    <div>      <app-locale-switcher />      <a href="https://vite.dev" target="_blank">        <img src="/vite.svg" class="logo" alt="Logo Vite" />      </a>      <a href="https://angular.dev/" target="_blank">        <img          src="/assets/angular.svg"          class="logo angular"          alt="Logo Angular"        />      </a>    </div>    <app-hello-world />  `,})export class AppComponent {}

    (Opzionale) Passo 7: Aggiungi il routing localizzato alla tua applicazione

    Aggiungere il routing localizzato in un'applicazione Angular implica l'uso di Angular Router con prefissi di localizzazione. Questo crea rotte uniche per ogni lingua, utile per la SEO.

    Esempio:

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

    Per prima cosa, assicurati di avere installato @angular/router.

    Poi, crea una configurazione del router che gestisca il routing basato sulla localizzazione in app.routes.ts.

    src/app/app.routes.ts
    import { Routes } from "@angular/router";import { configuration, localeFlatMap } from "intlayer";import { HomeComponent } from "./home/home.component";import { RootComponent } from "./root/root.component";const { defaultLocale } = configuration.internationalization;export const routes: Routes = [  localeFlatMap((localizedData) => [    {      path: `${localizedData.urlPrefix}`,      component: RootComponent,      data: { locale: localizedData.locale },    },    {      path: `${localizedData.urlPrefix}/home`,      component: HomeComponent,      data: { locale: localizedData.locale },    },  ]),  { path: "**", redirectTo: `/${defaultLocale}/home` },];

    Quindi, devi fornire il router nel tuo app.config.ts.

    src/app/app.config.ts
    import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [provideRouter(routes)],};

    (Opzionale) Passo 8: Cambiare l'URL quando cambia la lingua

    Per aggiornare automaticamente l'URL quando l'utente cambia lingua, puoi modificare il componente LocaleSwitcher per usare il Router di Angular:

    src/app/components/locale-switcher.component.ts
    import { Component, inject } from "@angular/core";import { CommonModule } from "@angular/common";import { Router } from "@angular/router";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "angular-intlayer";import { FormsModule } from "@angular/forms";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule, FormsModule],  template: `    <div class="locale-switcher">      <select [ngModel]="locale()" (ngModelChange)="changeLocale($event)">        <option *ngFor="let loc of availableLocales" [value]="loc">          {{ getLocaleName(loc) }}        </option>      </select>    </div>  `,})export class LocaleSwitcherComponent {  private router = inject(Router);  localeInfo = useLocale({    onLocaleChange: (newLocale) => {      const currentPath = this.router.url;      const localizedPath = getLocalizedUrl(currentPath, newLocale);      this.router.navigateByUrl(localizedPath);    },  });  locale = this.localeInfo.locale;  availableLocales = this.localeInfo.availableLocales;  getLocaleName = getLocaleName;  changeLocale(newLocale: string) {    this.localeInfo.setLocale(newLocale);  }}

    (Opzionale) Passo 9: Cambiare gli attributi di lingua e direzione dell'HTML

    Quando la tua applicazione supporta più lingue, è fondamentale aggiornare gli attributi lang e dir del tag <html> per riflettere la locale corrente.

    Puoi creare un servizio per gestire questo automaticamente.

    src/app/services/i18n-html-attributes.service.ts
    import { Injectable, effect } from "@angular/core";import { useLocale } from "angular-intlayer";import { getHTMLTextDir } from "intlayer";@Injectable({  providedIn: "root",})export class I18nHtmlAttributesService {  private localeInfo = useLocale();  constructor() {    effect(() => {      const newLocale = this.localeInfo.locale();      if (newLocale) {        document.documentElement.lang = newLocale;        document.documentElement.dir = getHTMLTextDir(newLocale);      }    });  }  // Questo metodo può essere chiamato nel componente radice dell'app per assicurarsi che il servizio sia inizializzato.  init() {}}

    Quindi, inietta e inizializza questo servizio nel tuo componente principale AppComponent:

    src/app/app.component.ts
    import { Component, inject } from "@angular/core";// ... altri importimport { I18nHtmlAttributesService } from "./services/i18n-html-attributes.service";@Component({  // ...})export class AppComponent {  constructor() {    inject(I18nHtmlAttributesService).init();  }}

    Per garantire che la navigazione della tua applicazione rispetti la lingua corrente, puoi creare una direttiva personalizzata. Questa direttiva aggiunge automaticamente il prefisso della lingua corrente agli URL interni.

    src/app/directives/localized-link.directive.ts
    import { Directive, Input, HostBinding, inject } from "@angular/core";import { getLocalizedUrl } from "intlayer";import { useLocale } from "angular-intlayer";@Directive({  selector: "a[appLocalizedLink]",  standalone: true,})export class LocalizedLinkDirective {  @Input("href") originalHref: string = "";  private localeInfo = useLocale();  @HostBinding("href")  get localizedHref(): string {    const locale = this.localeInfo.locale();    const isExternalLink = /^https?:\/\//.test(this.originalHref);    if (isExternalLink || !this.originalHref) {      return this.originalHref;    }    return getLocalizedUrl(this.originalHref, locale);  }}

    Per utilizzarlo, aggiungi la direttiva appLocalizedLink ai tuoi tag anchor e assicurati di importarla nel tuo componente.

    src/app/app.component.ts
    // ...import { LocalizedLinkDirective } from "./directives/localized-link.directive";@Component({  selector: "app-root",  standalone: true,  imports: [/*...,*/ LocalizedLinkDirective],  template: ` <a href="/home" appLocalizedLink>Home</a> `,})export class AppComponent {}

    (Opzionale) Passo 11: Renderizzare Markdown

    Intlayer supporta il rendering di contenuti Markdown. Per convertire Markdown in HTML ricco, puoi integrare markdown-it.

    Per prima cosa, installa markdown-it:

    bash
    npm install markdown-it# e i suoi tipinpm install -D @types/markdown-it

    Successivamente, configura il INTLAYER_MARKDOWN_TOKEN nel tuo app.config.ts.

    src/app/app.config.ts
    import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { routes } from "./app.routes";import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";import MarkdownIt from "markdown-it";const md = new MarkdownIt({  html: true,  linkify: true,  typographer: true,});export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    createIntlayerMarkdownProvider((markdown) => md.render(markdown)),  ],};

    Per impostazione predefinita, Intlayer restituisce l'HTML renderizzato come stringa. Se usi [innerHTML] per il binding, fai attenzione alle implicazioni di sicurezza (XSS). Assicurati sempre che il contenuto provenga da una fonte attendibile.

    Per scenari più complessi, puoi creare una pipe per rendere l'HTML in modo sicuro.

    Configurare TypeScript

    Intlayer utilizza l'augmentation dei moduli per sfruttare i vantaggi di TypeScript e rendere il tuo codice più robusto.

    alt text

    alt text

    Assicurati che la configurazione di TypeScript includa i tipi generati automaticamente.

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

    Configurazione Git

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

    Per farlo, puoi aggiungere le seguenti istruzioni al tuo file .gitignore:

    plaintext
    # Ignora i file generati da Intlayer.intlayer

    Estensione VS Code

    Per migliorare la tua esperienza di sviluppo con Intlayer, puoi installare la Estensione ufficiale Intlayer per VS Code.

    Installa dal Marketplace di VS Code 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 dell’estensione Intlayer per VS Code.


    Vai oltre

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


    Cronologia del documento

    • 5.5.10 - 2025-06-29: Inizio cronologia
    Ricevi notifiche sui prossimi lanci di Intlayer