@corellia/ngx-translation-io NPM

Translation.io for Angular

Add this package to localize your Angular application.

Il permet de simplifier la traduction des fichiers XLIFF 1.2 en passant par une interface simple et épurée. Aucune modification des fichiers XLIFF n'est nécessaire.

Cette solution fonctionne avec les versions d'Angular >= 13 Le package supporte uniquement les versions XLIFF 1.2.

Si vous avez besoin de plus d'informations sur l'internationalisation, veuillez consulter la documentation officielle.

Avant de commencer
- ng-extract-i18n-merge
- Générer les fichiers XLIFF
Type de traduction
Installation
Configuration
Usage
Exemple
License

Avant de commencer

ng-extract-i18n-merge

Il est nécessaire d'utiliser le package ng-extract-i18n-merge afin de générer correctement et facilement les différents fichiers de traductions nécessaires au bon fonctionnement de ce package.

Si vous desirez des explications détaillées sur l'installation du package, veuillez consulter son git.

Ajouter le package

ng add ng-extract-i18n-merge

Why ?

Pour éviter de faire cette partie de la documentation officielle à la main :

https://angular.io/guide/i18n#create-the-translation-files

Once the package is installed, it will add some configurations in the "angular.json" file

Fichier : 'angular.json' Exemple-ng-extract-i18n-merge

Voici les options obligatoires à configurer pour le package :

{
    "extract-i18n": {
        "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
        "options": {
            "browserTarget": "angular-tio-example:build:build",
            "format": "xlf",
            "includeContext": true,
            "outputPath": "src/locale",
            "targetFiles": [
                "messages.fr.xlf",
                "messages.nl.xlf",
                "messages.en.xlf"
            ]
        }
    }
}

La propriété "targetFiles" est la seule propriétée qui doit réellement être modifiée en fonction de votre configuration :

targetFiles : Les différentes langues de votre site
- Exemples :
  - le site est en français, anglais et néerlandais ===> "messages.fr.xlf", "messages.en.xlf", "messages.nl.xlf"
  - le site est en anglais et espagnol ===> "messages.en.xlf", "messages.es.xlf"

Générer les fichiers XLIFF

Pour utiliser le package ngx-translation-io, il faut posséder les différents fichier XLIFF. Un fichier XLIFF par langue.

Afin de générer ces fichiers, il y a une seule étape : 1. Générer le fichier de traductions de base avec la commande que fourni Angular ===> "extract-i18n". Cette commande étant override par la librarie ng-extract-i18n-merge, elle vous créera tous les fichiers XLIFF

Pour ce faire, il suffit d'ajouter une commande dans le package.json de votre Angular application

    "i18n": "ng extract-i18n"

Type de traduction

Il est important de savoir qu'il y a deux types de traductions sur Translation.io. Une traduction de type "KEY" et une traduction de type "SOURCE".

Si vous décidez d'utiliser les tags "i18n" avec des id personnalisés, c'est que vous dirigez vers l'approche de type "KEY".

Key

Il se base sur un id que vous lui donnez.
Cet id doit obligatoirement commencer par l'i18n_key
Pour modifier le contenu "Hello key", il faut obligatoirement utiliser l'interface graphique Translation.io.
Exemple :

    <div i18n="@@TIO_MYAPP_HelloKey">Hello key</div>

    helloKeyFromJS = $localize`:@@TIO_MYAPP_HelloKeyJS: Hello key from JS`

:warning: Si vous ne commencez pas vos id personnalisés par l'i18n_key, vos traductions seront traitées comme étant des traductions de type "SOURCE" et non de type "KEY".

Source

Il se base sur son contenu, son texte.
Aucun id ne doit être spécifié, il suffit de mettre le tag "i18n".
Pour modifier le contenu "Hello source", il suffit de changer le texte présent dans la balise.
- Une fois modifiée, la source devient alors une "nouvelle" traduction qu'il faut aller traduire dans Translation.io
Exemple

    <div i18n>Hello source</div>

    helloSourceFromJS = $localize `Hello source from JS`

Installation

Une fois que vous avez vos fichiers de traductions, il suffit d'installer le package NPM et de le configurer

npm i @corellia/ngx-translation-io@latest

Configuration

Go to your Translation.io account page and create a new project. Once the project is created, you'll have to create a configuration file in the root folder of your Angular app

Fichier : 'tio.config.json'

{
    "api_key": "YOUR API KEY",
    "i18n_key": "TIO",
    "source_language": {
        "language": "fr",
        "file": "./src/locale/messages.fr.xlf"
    },
    "target_languages": [
        {
            "language": "en",
            "file": "./src/locale/messages.en.xlf"
        },
        {
            "language": "nl",
            "file": "./src/locale/messages.nl.xlf"
        },
    ]
}

api_key : La clé API votre projet Translation.io
i18n_key : Préfix à utiliser pour chaque traduction qui utilise le système "KEY". Voir exemples.
source_language : La configuration de la source, c'est à dire, la langue principale du site. Il faut renseigner le code de la langue et l'emplacement du fichier correspondant.
- language : Le code de la langue source. (Le code doit être le même que celui indiqué dans Translation.io)
- file : Where is located your source XLIFF file
target_languages : La configuration des targets, c'est à dire, les autres langues du site. Pour chaque target, Il faut renseigner le code de la langue et l'emplacement du fichier correspondant.
- language : Le code de la langue target. (Le code doit être le même que celui indiqué dans Translation.io)
- file : Where is located your target XLIFF file

Proxy

Il est possible de définir un proxy, pour cela, rien de plus simple :

Fichier : 'tio.config.json'

{
    "api_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab",
    "i18n_key": "TIO",
    .
    .
    .
    "proxy": "http://1.1.1.1:8080"
}

Utilisation du préfix

Si le préfix n'est pas correctement utilisé, la traduction sera définie comme type "SOURCE"

    <div i18n="@@TIOHelloWorld"></div>      <!-- GOOD   ->  Traduction de type "KEY" -->
    <div i18n="@@TIO_HelloWorld"></div>     <!-- GOOD   ->  Traduction de type "KEY" -->

    <div i18n></div>                        <!-- WRONG  ->  Traduction de type "SOURCE" -->
    <div i18n="Goodbye"></div>              <!-- WRONG  ->  Traduction de type "SOURCE" -->
    <div i18n="@@Goodbye"></div>            <!-- WRONG  ->  Traduction de type "SOURCE" -->
    <div i18n="@@TI_O_Goodbye"></div>       <!-- WRONG  ->  Traduction de type "SOURCE" -->

    helloKeyFromJS = $localize`:@@TIOHelloWorldJS: Hello key from JS`;      // GOOD  ->  Traduction de type "KEY"
    helloKeyFromJS = $localize`:@@TIO_HelloWorldJS: Hello key from JS`;     // GOOD  ->  Traduction de type "KEY"

    helloKeyFromJS = $localize `Hello key from JS`;                         // WRONG ->  Traduction de type "SOURCE"
    helloKeyFromJS = $localize`:GoodbyeJS: Hello key from JS`;              // WRONG ->  Traduction de type "SOURCE"
    helloKeyFromJS = $localize`:@@GoodbyeJS: Hello key from JS`;            // WRONG ->  Traduction de type "SOURCE"
    helloKeyFromJS = $localize`:@@TI_O_GoodbyeJS: Hello key from JS`;       // WRONG ->  Traduction de type "SOURCE"

Usage

Init

Itialize your project and push existing translations to Translation.io with :

npm run tio --init --options=tio.config.json

Cette commande est, en principe, utilisé qu'une seule fois par projet. Elle permet d'initialiser les traductions existantes dans Translation.io. Pour toutes les autres actions, voir le SYNC

Sync

To send new translatable keys/strings and get new translations from Translation.io, simply run :

npm run tio --sync --options=tio.config.json

Pour les nouvelles traductions, il sera nécessaire de faire deux Syncs.
Le premier Sync va envoyer les nouvelles traductions sur Translation.io
Une fois que c'est traduit sur le site, le deuxième Sync va récupérer les traductions

Sync & Purge

If you need to remove unused keys/strings from Translation.io, using the current application as reference.

npm run tio --sync --purge --options=tio.config.json

As the name says, this operation will also perform a sync at the same time.

Warning : all keys that are not present in the current application will be permanently deleted from Translation.io.

Sync & Readonly

Si vous avez besoin de synchroniser sans modifier les données présentes dans Translation.io

npm run tio --sync --readonly --options=tio.config.json

La librairie va récupérer les traductions existantes sans

ajouter les nouveaux segments
mettre à jours les segments présents

Exemple

Init d'un projet

Dés que vous avez vos fichiers XLIFF, il ne reste plus qu'à initialiser votre projet Translation.io

Pour cela, il suffit de lancer une commande :

elle va générer les fichiersx XLIFF
et initialiser le projet sur Translation.io

build-i18n-and-translationio-init

Fichier : 'package.json' Exemple-init

Mettre à jour un projet

Pour mettre à jour les traductions, c'est très simple :

Il suffit de lancer une commande :

elle va générer les fichiersx XLIFF
et synchroniser les nouvelles traductions et/ou modifications avec Translation.io

build-i18n-and-translationio-sync

Fichier : 'package.json' Exemple-sync

Build complet d'une APP en plusieurs langues

Voici un exemple complet pour build une application dans chaque langue.

Il suffit de lancer une commande :

elle va générer les fichiersx XLIFF
synchroniser avec Translation.io
et build le projet avec les différentes traductions récupérées

npm run build

Fichier : 'package.json' Exemple-build

*N'oubliez pas de configurer le fichier "angular.json" avec les differentes configurations par langue pour pour que l'exemple fonctionne. Vous pouvez trouver un exemple complet dans le projet "sample" du repository.