Premiers pas avec l’internationalisation (i18n) dans Angular avec Intlayer

Ce package est en cours de développement. Consultez le problème pour plus d’informations. Montrez votre intérêt pour Intlayer pour Angular en aimant ce problème.

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 des composants.
• Localiser dynamiquement les métadonnées, les routes et le contenu.
• Assurer la prise en charge de TypeScript avec des types générés automatiquement, 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 dynamiques de la locale.

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

Étape 1 : Installer les dépendances

Installez les paquets nécessaires avec npm :

npm install intlayer angular-intlayer @intlayer/webpack

• intlayer

  Le package principal qui fournit des 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 package qui intègre Intlayer avec une application Angular. Il fournit des fournisseurs de contexte et des hooks pour l'internationalisation Angular.

• @intlayer/webpack Le package qui intègre Intlayer avec Webpack. Il est utilisé par l’Angular CLI pour construire les fichiers de déclaration de contenu et les surveiller en mode développement.

Étape 2 : Configuration de votre projet

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

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Vos autres locales    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Grâce à ce fichier de configuration, vous pouvez configurer des URL localisées, la redirection via middleware, les noms de cookies, l'emplacement et l'extension de vos déclarations de contenu, désactiver les logs Intlayer dans la console, et bien 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 l'Angular CLI, vous avez deux options selon votre builder : esbuild ou webpack.

Option 1 : Utiliser esbuild (recommandé)

Commencez par modifier votre angular.json pour utiliser le builder esbuild personnalisé. Mettez à jour la configuration build :

{  "projects": {    "your-app-name": {      "architect": {> Grâce à ce fichier de configuration, vous pouvez configurer des URL localisées, la redirection via middleware, les noms de cookies, l’emplacement et l’extension de vos déclarations de contenu, désactiver les logs Intlayer dans la console, et bien plus encore. Pour une liste complète des paramètres disponibles, consultez la [documentation de configuration](/fr/doc/concept/configuration).### Étape 3 : Intégrer Intlayer dans votre configuration AngularPour intégrer Intlayer avec Angular CLI, vous avez deux options selon votre builder : `esbuild` ou `webpack`.#### Option 1 : Utiliser esbuild (recommandé)Commencez par modifier votre `angular.json` pour utiliser le builder personnalisé esbuild. Mettez à jour la configuration `build` :```json fileName="angular.json"{  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application",          "options": {            "plugins": ["./esbuild/intlayer-plugin.ts"]          }        }      }    }  }}

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

Ensuite, créez un fichier esbuild/intlayer-plugin.ts à la racine de votre projet :

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 démarré", {        level: "info",      });      if (build.initialOptions.watch && !isWatching) {        logger("Mode surveillance activé. Démarrage du watcher...", {          level: "info",        });        watch(configuration);        isWatching = true;      }      try {        await prepareIntlayer(configuration);      } catch (error) {        logger(`Erreur dans le plugin Intlayer esbuild : ${error}`, {          level: "error",        });      }    });  },};export default intlayerPlugin;

Le intlayerPlugin pour esbuild garantit que Intlayer est préparé avant le démarrage de la compilation et surveille les changements en mode développement.

Option 2 : Utilisation de Webpack

Tout d'abord, modifiez votre fichier angular.json pour utiliser le builder Webpack personnalisé. Mettez à jour les configurations build et serve :

{  "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"        }      }    }  }}

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

Ensuite, créez un fichier webpack.config.js à la racine de votre projet :

const { IntlayerWebpackPlugin } = require("@intlayer/webpack");module.exports = {  plugins: [new IntlayerWebpackPlugin()],};

Le IntlayerWebpackPlugin est utilisé pour intégrer Intlayer avec Webpack. Il assure la génération des fichiers de déclaration de contenu et les surveille en mode développement. Il définit les variables d'environnement Intlayer dans l'application. De plus, il fournit des alias pour optimiser les performances.

Étape 4 : Déclarez Votre Contenu

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

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    title: t({      en: "Hello",      fr: "Bonjour",      es: "Hola",    }),    congratulations: t({      en: "Congratulations! Your app is running. 🎉",      fr: "Félicitations ! Votre application fonctionne. 🎉",      es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",    }),    exploreDocs: t({      en: "Explore the Docs",      fr: "Explorer la documentation",      es: "Explorar los Docs",    }),    learnWithTutorials: t({      en: "Learn with Tutorials",      fr: "Apprendre avec des tutoriels",      es: "Aprender con los Tutorios",    }),    cliDocs: "Documentation CLI",    angularLanguageService: t({      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;

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 correspondent à l'extension de fichier de déclaration de contenu (par défaut, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Pour plus de détails, référez-vous à la documentation sur la déclaration de contenu.

Étape 5 : Utiliser Intlayer dans votre code

Pour utiliser les fonctionnalités d'internationalisation d'Intlayer dans toute votre application Angular, vous devez utiliser la fonction useIntlayer au sein d'un composant. Cette fonction, disponible depuis angular-intlayer, donne accès à vos traductions sous forme de signaux réactifs.

IntlayerProvider est enregistré à la racine de l'application, vous n'avez donc pas besoin de l'ajouter aux providers de votre module.

Accédez à vos dictionnaires de contenu dans la classe de votre composant :

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

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

(Optionnel) É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 locale 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 { 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;  // Expose getLocaleName to the template  getLocaleName = getLocaleName;  changeLocale(newLocale: string) {    this.localeInfo.setLocale(newLocale);  }}Ensuite, utilisez ce composant dans votre `app.component.ts` :```typescript fileName="src/app/app.component.ts"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 {}

(Optionnel) Étape 7 : Ajouter un routage localisé à votre application

Ajouter un routage localisé dans une application Angular consiste à utiliser le routeur Angular avec des préfixes de locale. Cela crée des routes uniques pour chaque langue, ce qui est utile pour le référencement (SEO).

Exemple :

- https://example.com/about- https://example.com/es/about- https://example.com/fr/about

Tout d'abord, assurez-vous d'avoir installé @angular/router.

Ensuite, créez une configuration de routeur qui gère le routage basé sur la locale dans app.routes.ts.

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` },];

Ensuite, vous devez fournir le routeur dans votre fichier app.config.ts.

import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [provideRouter(routes)],};

(Optionnel) Étape 8 : Modifier l’URL lorsque la langue change

Pour mettre à jour automatiquement l’URL lorsque l’utilisateur change de langue, vous pouvez modifier le composant LocaleSwitcher pour utiliser le Router d’Angular :

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

(Optionnel) Étape 9 : Modifier les attributs lang et dir de la balise HTML

Lorsque votre application prend en charge plusieurs langues, il est essentiel de mettre à jour les attributs lang et dir de la balise <html> pour qu'ils correspondent à la locale actuelle.

Vous pouvez créer un service pour gérer cela automatiquement.

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);      }    });  }  // Cette méthode peut être appelée dans le composant racine de l'application pour s'assurer que le service est initialisé.  init() {}}

Ensuite, injectez et initialisez ce service dans votre composant principal AppComponent :

import { Component, inject } from "@angular/core";// ... autres importsimport { I18nHtmlAttributesService } from "./services/i18n-html-attributes.service";@Component({  // ...})export class AppComponent {  constructor() {    inject(I18nHtmlAttributesService).init();  }}

(Optionnel) Étape 10 : Création d'une directive de lien localisée

Pour garantir que la navigation de votre application respecte la langue actuelle, vous pouvez créer une directive personnalisée. Cette directive préfixe automatiquement les URL internes avec la langue courante.

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

Pour l'utiliser, ajoutez la directive appLocalizedLink à vos balises d'ancrage et assurez-vous de l'importer dans votre composant.

// ...import { LocalizedLinkDirective } from "./directives/localized-link.directive";@Component({  selector: "app-root",  standalone: true,  imports: [/*...,*/ LocalizedLinkDirective],  template: ` <a href="/home" appLocalizedLink>Accueil</a> `,})export class AppComponent {}

(Optionnel) Étape 11 : Rendre du Markdown

Intlayer prend en charge le rendu du contenu Markdown. Pour convertir du Markdown en HTML enrichi, vous pouvez intégrer markdown-it.

Commencez par installer markdown-it :

npm install markdown-it# et ses typesnpm install -D @types/markdown-it

Ensuite, configurez le INTLAYER_MARKDOWN_TOKEN dans votre fichier app.config.ts.

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)),  ],};

Par défaut, Intlayer renverra le HTML rendu sous forme de chaîne de caractères. Si vous utilisez [innerHTML] pour le lier, soyez conscient des implications en matière de sécurité (XSS). Assurez-vous toujours que votre contenu provient d'une source fiable.

Pour des scénarios plus complexes, vous pouvez créer un pipe pour rendre le HTML en toute sécurité.

Configurer TypeScript

Intlayer utilise l'augmentation de module pour bénéficier de TypeScript et renforcer votre base de code.

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

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

Configuration Git

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

Pour ce faire, vous pouvez ajouter les instructions suivantes dans 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 pour VS Code.

Installer depuis le Marketplace VS Code Cette extension offre :

• Autocomplétion pour les clés de traduction.
• Détection d'erreurs en temps réel pour les traductions manquantes.
• Aperçus en ligne du contenu traduit.
• 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 Intlayer pour VS Code.

Aller plus loin

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

Historique du document

• 5.5.10 - 2025-06-29 : Historique initial