Documentation

Configuration initiale

Commencez par ajouter le package de localisation d'Angular à votre projet :

ng add @angular/localize

Cette commande apportera les modifications suivantes :

  • Ajoute le package @angular/localize à vos dépendances.
  • Ajoute "@angular/localize/init" au tableau des polyfills dans angular.json
  • Ajoute la référence suivante à votre main.ts :
/// <reference types="@angular/localize" />

Il ajoutera également la configuration extract-i18n à angular.json :

"extract-i18n": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "your-app:build",
    "format": "xlf",
    "outputPath": "src/locale",
    "includeContext": true,
    "resetTranslationState": true,
    "targetFiles": [
      "messages.fr.xlf",
      "messages.vi.xlf"
    ]
  }
}

Note : Nous modifierons le outputPath plus tard dans la configuration pour l'adapter à notre flux de travail.

Angular i18n CLI Tool

To simplify the management of Angular i18n configuration, you can use our CLI tool:

npm install --save-dev @softwarity/angular-i18n-cli

This tool provides several features to streamline your i18n workflow:

  • Easy initialization of i18n configuration in your Angular project
  • Simple addition and removal of locales
  • Automatic configuration of build settings for each locale
  • Proper setup of XLIFF file formats

Angular i18n CLI

CLI tool to simplify Angular i18n configuration and locale management.

Installer l'outil de traduction

Pour gérer les fichiers de traduction, nous utiliserons ng-extract-i18n-merge qui simplifie le processus d'extraction et de fusion des traductions :

npm install --save-dev ng-extract-i18n-merge

Cet outil offre plusieurs avantages :

  • Extrait automatiquement les chaînes traduisibles de votre application
  • Fusionne les nouvelles traductions avec celles existantes en une seule étape
  • Préserve les traductions existantes lors des mises à jour
  • Prend en charge plusieurs langues cibles

Fichiers de configuration

package.json

"scripts": {
  ...
  "extract-i18n": "ng extract-i18n",
  "build": "ng build --localize"
  ...
}

angular.json

Mettez à jour la configuration i18n dans angular.json :

"i18n": {
  "sourceLocale": "en",
  "locales": {
    "fr": {
      "translation": "src/locale/messages.fr.xlf"
    },
    "vi": {
      "translation": "src/locale/messages.vi.xlf"
    }
  }
},

Remplacez la configuration standard de extract-i18n par ng-extract-i18n-merge :

"extract-i18n": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "your-app:build",
    "format": "xlf",
    "outputPath": "src/locale",
    "includeContext": true,
    "resetTranslationState": true,
    "targetFiles": [
      "messages.fr.xlf",
      "messages.vi.xlf"
    ]
  }
}

Options de configuration importantes :

  • nom de la cible de construction : Le nom de la cible de construction de votre application
  • cheminDeSortie: Répertoire où les fichiers de traduction seront stockés
  • inclureContexte : Inclut les informations sur le fichier source dans les fichiers XLIFF
  • réinitialiser l'état de traduction : Indique que toutes les traductions doivent être révisées lors des modifications
  • fichiers cibles: Liste des fichiers de traduction à générer/mettre à jour

Build configurations

Ajoutez des configurations pour chaque langue dans la section de construction :

"architect": {
  "build": {
    "configurations": {
      "fr": {
        "localize": ["fr"]
      },
      "vi": {
        "localize": ["vi"]
      }
    }
  }
}

Préparer les composants pour la traduction

Pour préparer vos composants à la traduction, vous devez marquer le texte qui doit être traduit. Angular fournit deux méthodes pour ce faire :

Documentation Angular : Marquage de texte pour la traduction

En savoir plus sur la préparation de votre application pour la traduction.

Traduction de Template

Utilisez l'attribut i18n dans vos modèles pour marquer le texte à traduire :

<tag attribute="This is a sample attribute text that needs translation." 
  i18n-attribute="@@ATTRIBUTE_TEXT"
  i18n="@@TAG_TEXT">This is a sample text that needs translation.</tag>
// EXAMPLE
<button title="Title button" i18n-title="@@TITLE_BUTTON"i18n="@@LABEL_BUTTON">label button</button>

Le @@prefix définit un identifiant personnalisé pour la traduction. L'utilisation de SNAKE_CASE est recommandée pour assurer la cohérence.

Traduction de « Component Translation » : Titre de la traduction du composant

Pour le texte dans votre code de composant, utilisez l'étiquette de modèle $localize :

import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: '...'
})
export class ExampleComponent {
  title = $localize`:@@PAGE_TITLE:Welcome to our application`;
  errorMessage = $localize`:@@ERROR_MESSAGE:An error occurred while processing your request`;
}

Construction et Service

Construire avec des traductions

Construisez votre application avec toutes les traductions :

npm run build

Ou construisez pour une langue spécifique (utilisant le français comme exemple) :

ng build --configuration=fr

Serveur de développement

Servez votre application avec des traductions pendant le développement :

ng serve --configuration=fr

⚠️ Remarque importante

Après avoir ajouté de nouveaux contenus traduisibles ou modifié des traductions existantes :

  1. ng extract-i18n - pour extraire et mettre à jour tous les fichiers de traduction en une seule étape

Ce workflow simplifié garantit que vos fichiers de traduction sont toujours à jour avec le contenu source, rendant le processus d'internationalisation plus efficace et sans erreurs.