Traduisez votre site Angular 21 (Vite) avec Intlayer | Internationalisation (i18n)

Table des matières

Qu'est-ce qu'Intlayer ?

Intlayer est une bibliothèque d'internationalisation (i18n) innovante et open-source conçue pour simplifier la prise en charge multilingue dans les applications web modernes.

Avec Intlayer, vous pouvez :

• Gérer facilement les traductions en utilisant des dictionnaires déclaratifs au niveau du composant.
• Localiser dynamiquement les métadonnées, les routes et le contenu.
• Garantir le support TypeScript avec des types autogénérés, améliorant l'autocomplétion et la détection d'erreurs.
• Bénéficier de fonctionnalités avancées, comme la détection et le changement de locale dynamiques.

Guide étape par étape pour configurer Intlayer dans une application Angular

Voir Modèle d'Application sur GitHub.

Étape 1 : Installer les dépendances

Installez les paquets nécessaires en utilisant npm :

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

• intlayer

  Le paquet principal qui fournit les outils d'internationalisation pour la gestion de la configuration, la traduction, la déclaration de contenu, la transpilation, et les commandes CLI.

• angular-intlayer Le paquet qui intègre Intlayer avec l'application Angular. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation Angular.

• @angular-builders/custom-esbuild Requis pour personnaliser la configuration esbuild d'Angular CLI.

Étape 2 : Configuration de votre projet

Créez un fichier de configuration pour configurer les langues de votre application :

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Vos autres langues
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Via ce fichier de configuration, vous pouvez configurer les URL localisées, la redirection de middleware, les noms de cookies, l'emplacement et l'extension de vos déclarations de contenu, désactiver les journaux Intlayer dans la console, et plus encore. Pour une liste complète des paramètres disponibles, consultez la documentation de configuration.

Étape 3 : Intégrer Intlayer dans votre configuration Angular

Pour intégrer Intlayer avec Angular CLI, vous devez utiliser un builder personnalisé. Ce guide suppose que vous utilisez Vite/esbuild (par défaut pour les projets Angular 21).

D'abord, modifiez votre angular.json pour utiliser le builder esbuild personnalisé. Mettez à jour les configurations build et 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"              ]          },        },      },    },  },}

Assurez-vous de remplacer your-app-name par le nom réel de votre projet dans angular.json.

Ensuite, créez un fichier esbuild.plugins.ts à la racine de votre projet :

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

La fonction intlayerEsbuildPlugin configure esbuild avec Intlayer. Elle injecte le plugin pour gérer les fichiers de déclaration de contenu et configure les éléments pour des performances optimales.

Utilisateurs de NX : Les builders Angular de NX chargent les fichiers de plug-in via la résolution ESM native de Node et ne compilent pas les fichiers de plug-in TypeScript à la volée. Utilisez plutôt un fichier .mjs et mettez à jour la référence plugins dans angular.json en conséquence :

esbuild.plugins.mjs

Copier le contenu

Copier le code

Copier le code dans le presse-papiers

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

Ensuite, dans angular.json, pointez vers "./esbuild.plugins.mjs" au lieu de "./esbuild.plugins.ts".

Étape 4 : Déclarez votre contenu

Créez et gérez vos déclarations de contenu pour stocker les traductions :

Vos déclarations de contenu peuvent être définies n'importe où dans votre application dès qu'elles sont incluses dans le répertoire contentDir (par défaut, ./src). Et qu'elles correspondent à l'extension de fichier de déclaration de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Pour plus de détails, consultez la documentation sur les déclarations de contenu.

Étape 5 : Utiliser Intlayer dans votre code

Pour utiliser les fonctionnalités d'internationalisation d'Intlayer dans votre application Angular, vous devez fournir Intlayer dans la configuration de votre application.

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(), // Ajoutez le fournisseur Intlayer ici  ],};

Ensuite, vous pouvez utiliser la fonction useIntlayer dans n'importe quel composant.

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

Et dans votre modèle :

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

Le contenu Intlayer est retourné sous forme de Signal, donc vous accédez aux valeurs en appelant le signal : content().title.

(Facultatif) Étape 6 : Changer la langue de votre contenu

Pour changer la langue de votre contenu, vous pouvez utiliser la fonction setLocale fournie par la fonction useLocale. Cela vous permet de définir la langue de l'application et de mettre à jour le contenu en conséquence.

Créez un composant pour basculer entre les langues :

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

Ensuite, utilisez ce composant dans votre 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");}

Configurer TypeScript

Intlayer utilise l'augmentation de module pour tirer parti de TypeScript et rendre votre base de code plus robuste.

Assurez-vous que votre configuration TypeScript inclut les types autogénérés.

{  // ... Vos configurations TypeScript existantes  "include": [    // ... Vos configurations TypeScript existantes    ".intlayer/**/*.ts", // Inclure les types autogénérés  ],}

Configuration Git

Il est recommandé d'ignorer les fichiers générés par Intlayer. Cela vous permet d'éviter de les commiter dans votre dépôt Git.

Pour ce faire, vous pouvez ajouter les instructions suivantes à votre fichier .gitignore :

# Ignorer les fichiers générés par Intlayer.intlayer

Extension VS Code

Pour améliorer votre expérience de développement avec Intlayer, vous pouvez installer l'extension officielle Intlayer VS Code Extension.

Installer depuis le VS Code Marketplace

Cette extension fournit :

• L'autocomplétion pour les clés de traduction.
• La détection d'erreurs en temps réel pour les traductions manquantes.
• Des aperçus en ligne du contenu traduit.
• Des actions rapides pour créer et mettre à jour facilement les traductions.

Pour plus de détails sur l'utilisation de l'extension, consultez la documentation de l'extension VS Code Intlayer.

Aller plus loin

Pour aller plus loin, vous pouvez implémenter l'éditeur visuel ou externaliser votre contenu en utilisant le CMS.