Pose una domanda e ottieni un riassunto del documento facendo riferimento a questa pagina e al provider AI di tua scelta
Integrando il server MCP Intlayer al tuo assistente AI, puoi recuperare tutti i documenti direttamente da ChatGPT, DeepSeek, Cursor, VSCode, ecc.
Vedi la documentazione del server MCPIl contenuto di questa pagina è stato tradotto con un'IA.
Vedi l'ultima versione del contenuto originale in ingleseSe hai un’idea per migliorare questa documentazione, non esitare a contribuire inviando una pull request su GitHub.
Collegamento GitHub alla documentazioneCopia il Markdown del documento nella porta-documenti
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:
Copiare il codice nella clipboard
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:
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 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:
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 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:
Copiare il codice nella clipboard
{ "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:
Copiare il codice nella clipboard
{ "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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
{ "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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
- 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.
Copiare il codice nella clipboard
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.
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
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.
Copiare il codice nella clipboard
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:
Copiare il codice nella clipboard
import { Component, inject } from "@angular/core";// ... altri importimport { I18nHtmlAttributesService } from "./services/i18n-html-attributes.service";@Component({ // ...})export class AppComponent { constructor() { inject(I18nHtmlAttributesService).init(); }}
(Opzionale) Passo 10: Creare una direttiva per link localizzati
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.
Copiare il codice nella clipboard
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.
Copiare il codice nella clipboard
// ...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:
Copiare il codice nella clipboard
npm install markdown-it# e i suoi tipinpm install -D @types/markdown-it
Successivamente, configura il INTLAYER_MARKDOWN_TOKEN nel tuo app.config.ts.
Copiare il codice nella clipboard
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.
Assicurati che la configurazione di TypeScript includa i tipi generati automaticamente.
Copiare il codice nella clipboard
{ // ... 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:
Copiare il codice nella clipboard
# 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