Une instruction pratique étape par étape sur la façon d'accélérer la localisation dynamique (la possibilité de sélectionner des langues) dans une application Web Angular 4+ à l'aide de @ ngx-translate / core .
En principe, vous pouvez trouver des publications sur un sujet similaire, la documentation de cette bibliothèque peut être suffisante, mais je voulais systématiser cette instruction pour une application plus pratique. Un tel signet se trouve dans la tirelire d'un développeur Angular novice. À la fin de l'article, il y a un lien vers un référentiel ouvert avec un exemple.
Pourquoi exactement ngx-translate
Je veux faire une réservation tout de suite, ceci est une instruction pour utiliser une bibliothèque spécifique. Nous ne parlerons pas d'alternatives, que l'angulaire a sa propre localisation i18n. Ne serait-ce que parce qu'avec un changement de langue dynamique il y a des questions.
Qu'obtenons-nous à la sortie
- Application angulaire, dans le dossier
assets/locale il y a des fichiers *.json avec des clés et leurs valeurs localisées, un fichier pour chaque langue prise en charge dans l'application web. - Changement de langue dynamique
- Le stockage des clés dans une structure d'objet, c'est-à-dire, a quelque chose comme ceci:
// en.json { Common: { Yes: "Yes" } }
Cela vous permettra de regrouper les clés / valeurs et d'organiser en quelque sorte un fichier json avec localisation. Pour les grands projets, c'est très utile.
- Automatisation minimale et recherche d'un imbécile. Que faire si vous avez oublié d'ajouter la clé dans json?
- Application de la localisation à la fois dans les modèles html et dans le code ts
Personnaliser
Nous créons ou prenons un projet angulaire prêt. La version de l'angular est 4+, mais elle est bien sûr aussi fraîche que possible.
Installez les bibliothèques nécessaires:
npm install @ngx-translate/core --save npm install @ngx-translate/http-loader --save @biesbjerg/ngx-translate-extract --saveDev
La @ngx-translate/http-loader est nécessaire pour que nous puissions lire les données de localisation à partir des fichiers *.json . Vous pouvez vous en passer, mais vous devrez alors écrire le stockage et le chargement des données de localisation de manière complètement indépendante. Cette approche convient à ceux qui ont déjà des données de localisation (ou simplement tous les textes traduits) stockés quelque part.
La @biesbjerg/ngx-translate-extract est facultative, mais assez utile. Il vous permet de collecter les clés de localisation oubliées par code d'application et de mettre à jour les fichiers de localisation. Son utilisation est très pratique pour traiter un tel scénario: ajoutez une nouvelle langue et exécutez simplement la commande à partir de cette bibliothèque. Par conséquent, le fichier vide pour la nouvelle langue sera rempli avec la structure entière des clés et certaines valeurs par défaut. Un exemple sera ci-dessous.
- Importez la bibliothèque dans le module principal:
@NgModule({ imports: [ TranslateModule.forRoot({ loader: { provide: TranslateLoader, useFactory: HttpLoaderFactory, deps: [HttpClient], }, useDefaultLang: false, }) ], }) export class AppModule { }
La HttpLoaderFactory présente dans les HttpLoaderFactory la bibliothèque, elle peut être décrite directement dans le même fichier, elle est de taille modeste.
export function HttpLoaderFactory(http: HttpClient): TranslateLoader { return new TranslateHttpLoader(http, './assets/locale/', '.json'); }
C'est là que nous indiquons le chemin d'accès aux fichiers de localisation. S'ils sont stockés d'une manière ou d'une autre, ou même différemment dans différents environnements - changez ce code pour utiliser environment.ts par exemple.
- En principe, cela suffit pour les paramètres de base, mais nous prendrons une autre étape supplémentaire - la gestion des erreurs lorsque la clé n'est pas trouvée.
Pour ce faire, ajoutez un champ supplémentaire à la configuration (immédiatement après avoir spécifié le chargeur):
missingTranslationHandler: { provide: MissingTranslationHandler, useClass: MissingTranslationService },
Et bien sûr, vous devez créer l'implémentation de ce gestionnaire dans un fichier séparé:
export class MissingTranslationService implements MissingTranslationHandler { handle(params: MissingTranslationHandlerParams) { return `WARN: '${params.key}' is missing in '${params.translateService.currentLang}' locale`; } }
- Ajoutez un stockage des langues disponibles. Dans le cas simple, il est pratique de les mettre dans l'
environment.ts
locales: ['en', 'ru'], defaultLocale: 'en',
- Pour que le service commence à fonctionner, il doit être initialisé dans le fichier AppComponent lors du chargement de l'application:
@Component({...}) export class AppComponent implements OnInit { constructor(private translateService: TranslateService) {} ngOnInit(): void { this.translateService.use(environment.defaultLocale); } }
- Ajoutez les fichiers
en.json et ru.json (selon ce qui est indiqué dans la liste des langues disponibles). Ajoutez un champ de base pour qu'il soit valide json.
Une fois ces étapes effectuées, le service commencera à fonctionner.
Nous utilisons le service
Balisage HTML
Ici, tout est simple. La bibliothèque propose la translate pipe, nous l'appliquons simplement dans le balisage pour certaines clés.
<label>{{ 'LANGUAGES.TITLE' | translate }}</label>
Notez que j'utilise ici les propriétés attachées, la structure json dont j'ai parlé au début.
Les paramètres sont également pris en charge, regardez-les s'il vous plaît dans la documentation @ ngx-translate / core . À l'aide de paramètres, vous pouvez implémenter quelque chose comme l'interpolation de chaînes.
Dans le code composant
this.translateService.get(['KEY1', 'KEY2'])) .subscribe(translations => { console.log(translations['KEY1']) console.log(translations['KEY2']) });
C'est un moyen fiable si vous êtes normal avec Observable et RxJs.
Sinon, il existe un moyen:
this.translateService.instant('Key')
Cette méthode fonctionne bien, mais au stade de l'initialisation de l'application (par exemple, ngOnInit AppComponent), les données ne peuvent pas encore être chargées. Soyez prudent.
Prise en charge des fichiers .json
À la fin, je veux montrer comment utiliser l' ngx-translate-extract . Exécutez simplement la commande ngx-translate-extract -i ./src -o src/assets/locale/*.json --sort --format namespaced-json dans la console. Cette commande démarre l'analyse des fichiers d'application, du balisage et du code temporel. Toutes les clés trouvées dans le balisage et autres codes tomberont dans .json pour toutes les langues, les clés existantes et leurs valeurs resteront intactes, sauf que l'ordre peut changer.
Pour plus de commodité, j'ajoute ceci en tant que script dans package.json
"scripts": { "ng": "ng", "start": "ng serve", "update-locale": "ngx-translate-extract -i ./src -o src/assets/locale/*.json --sort --format namespaced-json" },
Tout ce que j'ai décrit peut être trouvé assemblé dans un référentiel ouvert: valentinkononov / ngx-translate-angular
J'espère que le matériel vous sera utile! Écrivez du code avec plaisir, choisissez des bibliothèques pratiques et réalisez des projets utiles!