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

Sommario

Cos'è Intlayer?

Intlayer è una libreria di internazionalizzazione (i18n) innovativa e open-source 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 metadati, rotte e contenuti.
• Garantire il supporto 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

Vedi il Modello di Applicazione su GitHub.

Passo 1: Installare le dipendenze

Installa i pacchetti necessari utilizzando npm:

npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx intlayer init

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

Passo 2: Configurazione del tuo progetto

Crea un file di configurazione per impostare le lingue della tua applicazione:

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.

Passo 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 21).

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

{  "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:

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

Copia contenuto

Copiare il codice

Copiare il codice nella clipboard

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

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

Passo 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}).

Per ulteriori dettagli, consulta la documentazione sulla dichiarazione dei contenuti.

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

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.

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:

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

(Opzionale) Passo 6: Cambia la lingua dei tuoi contenuti

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:

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:

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.

Assicurati che la tua configurazione TypeScript includa i tipi autogenerati.

{  // ... 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:

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