Traduci il tuo sito Angular 19 (Webpack) usando Intlayer | Internazionalizzazione (i18n)

Indice

Perché Intlayer rispetto alle alternative?

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

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

Vedi il Modello di Applicazione su GitHub.

1. 1

   Installa le dipendenze

   Installa i pacchetti necessari usando npm:

   bash

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   npm install intlayer angular-intlayer
   npm install @angular-builders/custom-webpack --save-dev
   

   • intlayer

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

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

   • @angular-builders/custom-webpack Richiesto per personalizzare la configurazione Webpack di Angular CLI.

2. 2

   Configurazione del progetto

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

   intlayer.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Altre lingue
       ],
       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 dichiarazioni dei contenuti, disabilitare i log di Intlayer nella console e altro ancora. Per un elenco completo dei parametri disponibili, consulta la documentazione della configurazione.

3. 3

   Integrare Intlayer nella configurazione Angular

   Per integrare Intlayer con Angular CLI, è necessario utilizzare un builder personalizzato. Questa guida presuppone l'utilizzo di Webpack (predefinito per molti progetti Angular).

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

   angular.json

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   {
     "projects": {
       "your-app-name": {
         "architect": {
           "build": {
             "builder": "@angular-builders/custom-webpack:browser", // replace "@angular-devkit/build-angular:application",
             "options": {
               "customWebpackConfig": {
                 "path": "./webpack.config.ts",
                 "mergeStrategies": { "module.rules": "prepend" },
               },
               "main": "src/main.ts", // replace "browser": "src/main.ts",
               // ...
             },
           },
           "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.ts nella radice del tuo progetto:

   webpack.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import { mergeConfig } from "angular-intlayer/webpack";
   
   export default mergeConfig({});
   

   La funzione mergeConfig configura Webpack con Intlayer. Inietta l'IntlayerPlugin (per gestire i file di dichiarazione dei contenuti) e imposta gli alias per prestazioni ottimali.

4. 4

   Dichiarare i contenuti

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

   Le dichiarazioni di contenuto possono essere definite ovunque nell'applicazione, a condizione che siano incluse nella directory contentDir (per impostazione predefinita, ./src) e corrispondano all'estensione del file di dichiarazione del contenuto (per impostazione predefinita, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

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

5. 5

   Utilizzare Intlayer nel codice

   Per utilizzare le funzionalità di internazionalizzazione di Intlayer in tutta la tua applicazione Angular, devi fornire Intlayer nella configurazione dell'applicazione.

   src/app/app.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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 il provider Intlayer qui
     ],
   };
   

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

   src/app/app.component.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

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

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

6. 6

   Cambiare la lingua dei contenuti

   Opzionale

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

   Crea un componente per cambiare lingua:

   src/app/locale-switcher.component.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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, usa questo componente nel tuo app.component.ts:

   src/app/app.component.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   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");
   }
   

Configura TypeScript

Intlayer utilizza l'aumento dei moduli per sfruttare i vantaggi di TypeScript e rendere la tua 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. Questo ti permette di evitare di caricarli nel tuo repository Git.

Per fare ciò, 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 VS Code Extension.

Installa dal VS Code Marketplace

Questa estensione offre:

• Autocompletamento per le chiavi di traduzione.
• Rilevamento degli errori in tempo reale per le traduzioni mancanti.
• Anteprime inline del contenuto tradotto.
• 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.

Approfondimenti

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

Domande frequenti