Traduci la tua app Analog (Angular) usando 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, percorsi e contenuti.
• Garantire il supporto TypeScript con tipi generati automaticamente, migliorando l'autocompletamento e il rilevamento degli errori.
• Beneficiare di funzionalità avanzate, come il rilevamento e la commutazione dinamica della lingua.

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

Vedi il Template dell'Applicazione su GitHub.

Passaggio 1: Installa le Dipendenze

Installa i pacchetti necessari utilizzando npm:

npm install intlayer angular-intlayer vite-intlayernpx intlayer init

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

Passaggio 2: Configurazione del tuo Progetto

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

Passaggio 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:

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";import analog from "@analogjs/platform";// https://vitejs.dev/config/export default defineConfig(() => ({  plugins: [    analog(),    intlayer(), // Aggiungi il plugin Intlayer  ],}));

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

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

Per maggiori dettagli, fai riferimento alla documentazione sulla dichiarazione dei contenuti.

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

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.

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.

(Opzionale) Passaggio 6: Cambia la lingua del tuo contenuto

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:

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:

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.