Traduci la tua app Analog (Angular) usando 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:

Guida Passo-Passo per Configurare Intlayer in un'Applicazione Analog

Vedi il Template dell'Applicazione su GitHub.

1. 1

   Installa le Dipendenze

   Installa i pacchetti necessari utilizzando 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 vite-intlayer
   

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

   • vite-intlayer Il pacchetto che integra Intlayer con Vite. Fornisce un plugin per gestire i file di dichiarazione dei contenuti e imposta gli alias per prestazioni ottimali.

2. 2

   Configurazione del tuo Progetto

   Crea un file di configurazione per configurare 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,
         // 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 della configurazione.

3. 3

   Integra Intlayer nella tua Configurazione Vite

   Per integrare Intlayer con Analog, devi utilizzare il plugin vite-intlayer.

   Modifica il tuo file vite.config.ts:

   vite.config.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   import analog from "@analogjs/platform";
   
   // https://vitejs.dev/config/
   export default defineConfig(() => ({
     plugins: [
       analog(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   }));
   

   Il plugin intlayer() configura Vite con Intlayer. Gestisce i file di dichiarazione dei contenuti e imposta gli alias per prestazioni ottimali.

4. 4

   Dichiarazione dei Contenuti

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

   Le tue dichiarazioni di contenuto possono essere definite ovunque nella tua applicazione purché 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, fai riferimento alla documentazione sulla dichiarazione dei contenuti.

5. 5

   Utilizza Intlayer nel tuo Codice

   Per utilizzare le funzionalità di internazionalizzazione di Intlayer in tutta la tua applicazione Analog, 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 { provideIntlayer } from "angular-intlayer";
   
   export const appConfig: ApplicationConfig = {
     providers: [
       provideIntlayer(), // Aggiungi il provider Intlayer qui
     ],
   };
   

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

   src/app/pages/index.page.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import { Component } from "@angular/core";
   import { useIntlayer } from "angular-intlayer";
   
   @Component({
     selector: "app-home",
     standalone: true,
     template: `
       <div class="content">
         <h1>{{ content().title }}</h1>
         <p>{{ content().congratulations }}</p>
       </div>
     `,
   })
   export default class HomeComponent {
     content = useIntlayer("app");
   }
   

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

6. 6

   Cambia la lingua del tuo contenuto

   Opzionale

   Per cambiare la lingua del tuo contenuto, puoi utilizzare la funzione setLocale fornita dalla funzione useLocale. Ciò ti consente di impostare la localizzazione dell'applicazione e aggiornare il contenuto di conseguenza.

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

   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 nelle tue pagine:

   src/app/pages/index.page.ts

   Copia contenuto

   Copiare il codice

   Copiare il codice nella clipboard

   import { Component } from "@angular/core";
   import { useIntlayer } from "angular-intlayer";
   import { LocaleSwitcherComponent } from "../locale-switcher.component";
   
   @Component({
     selector: "app-home",
     standalone: true,
     imports: [LocaleSwitcherComponent],
     template: `
       <app-locale-switcher></app-locale-switcher>
       <div class="content">
         <h1>{{ content().title }}</h1>
         <p>{{ content().congratulations }}</p>
       </div>
     `,
   })
   export default class HomeComponent {
     content = useIntlayer("app");
   }
   

Configura TypeScript

Intlayer utilizza l'aumento dei moduli (module augmentation) per trarre vantaggio da TypeScript e rendere più solida la tua base di codice.

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

{
  // ... 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. Ciò consente di evitare di caricarli nel 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 Intlayer per VS Code ufficiale.

Installa dal Marketplace di VS Code

Questa estensione fornisce:

• Autocompletamento per le chiavi di traduzione.
• Rilevamento degli errori in tempo reale per le traduzioni mancanti.
• Anteprime in linea 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 andare oltre, puoi implementare l'editor visuale o esternalizzare i tuoi contenuti utilizzando il CMS.

Domande frequenti