В какой-то момент вашему веб-приложению может потребоваться многоязычная пользовательская база. Но как ее обслуживать? Интернационализация, или сокращенно i18n, — это процесс, который позволяет сделать приложения доступными для людей, которые говорят на разных языках.
Angular имеет встроенные функции i18n, но лучше использовать сторонний пакет ngx-translate — он предлагает больше функций.
В этом мануале мы покажем, как использовать ngx-translate в приложении Angular.
Требования
- Локальная установка Node.js, которую можно получить, следуя инструкциям для вашего дистрибутива: Mac OS, Ubuntu, CentOS, Debian.
- Базовое знакомство с Angular и умение создавать проекты.
Это руководство было протестировано на версиях Node v16.4.0, npm v7.19.0, @angular/core v12.1.0, @ngx-translate/core v13.0.0 и @ngx-translate/http-loader v6.0.0.
Создание простого проекта
Создайте новое приложение Angular и добавьте в него несколько зависимостей.
Откройте терминал и используйте @angular/cli для создания нового проекта:
ng new angular-ngx-translate-example --skip-tests
Затем перейдите во новый каталог проекта:
cd angular-ngx-translate-example
Выполните следующую команду, чтобы добавить пакет в ваше приложение:
npm install @ngx-translate/core@13.0.0
Теперь импортируйте TranslateModule в свой AppModule:
import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { TranslateModule } from '@ngx-translate/core'; import { AppComponent } from './app.component'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, TranslateModule.forRoot() ], providers: [], bootstrap: [AppComponent] }) export class AppModule { }
Это обеспечит доступ к ядру сервиса-переводчика, а также к каналу и директивам.
Однако если вы не планируете добавлять каждый перевод вручную через код, на этом этапе вам нужно будет добавить немного конфигурации, чтобы упростить загрузку переводов в дальнейшем.
Использование TraslateHttpLoader
Вероятно, наиболее распространенным способом загрузки переводов – это включение файлов с переводами в качестве ресурсов и их загрузка с помощью плагина TranslateHttpLoader, который доступен в отдельном пакете npm.
npm install @ngx-translate/http-loader@6.0.0
Импортируйте TranslateHttpLoader в свой AppModule:
import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { HttpClientModule, HttpClient } from '@angular/common/http'; import { TranslateModule, TranslateLoader } from '@ngx-translate/core'; import { TranslateHttpLoader } from '@ngx-translate/http-loader'; import { AppComponent } from './app.component'; // AoT requires an exported function for factories export function HttpLoaderFactory(http: HttpClient) { return new TranslateHttpLoader(http); } @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, HttpClientModule, TranslateModule.forRoot({ loader: { provide: TranslateLoader, useFactory: HttpLoaderFactory, deps: [HttpClient] } }) ], providers: [], bootstrap: [AppComponent] }) export class AppModule { }
Вы также можете создать свой собственный загрузчик. Для этого нужно реализовать интерфейс TranslateLoader и предоставить его в своем модуле, как указано выше.
Использование файлов
Создание подобного загрузчика переводов предполагает наличие в вашем проекте файла в папке /assets/i18n/ по имени {lang}.json, где {lang} — это язык перевода. Например, файл с английским переводом может называться en.json.
Вы можете изменить путь и расширение файла по умолчанию, предоставив дополнительные параметры новому конструктору TranslateHttpLoader().
Файл перевода — это объект JSON, состоящий из пар ключ-значение, где ключ описывает текст, который переводится, а значение — это фактический текст перевода на другой язык.
{ "welcomeMessage": "Thanks for joining, {{ firstName }}! It's great to have you!", "login": { "username": "Enter your user name", "password": "Password here" } }
Значение также может быть другим объектом, который позволяет группировать переводы по вашему усмотрению.
В текст значения перевода вокруг имени переменной можно включить двойные фигурные скобки, что позже позволит вам динамически интерполировать строки в переводы.
Доступ к переводам
Прежде чем вы сможете получить доступ к переводам в своем приложении, вы должны инициализировать некоторые свойства в TranslateService.
Возможно, лучше всего это сделать в загруженном AppComponent (файл src/app/app.component.ts).
import { Component } from '@angular/core'; import { TranslateService } from '@ngx-translate/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { constructor(translate: TranslateService) { translate.addLangs(['en', 'klingon']); translate.setDefaultLang('en'); translate.use('en'); } }
Строка translate.addLangs([]) сообщает сервису, какие языки доступны для перевода.
Метод translate.setDefaultLang(‘en’) позволяет указать резервный набор переводов, который будет использоваться в случае отсутствия переводов для текущего языка.
translate.use(‘en’) сообщает сервису, какой язык использовать в качестве текущего для переводов.
Общим параметром для всех них будет исходный язык, с которого вашему приложению нужны переводы.
При такой настройке у вас есть три способа получить доступ к переводам. Какой из них вы используете в тот или иной момент, зависит только от ваших потребностей и предпочтений.
Использование TranslateService
Также вы можете получить переводы через сервис TranslateService, для этого существует два метода.
Первый и рекомендуемый метод:
get(key: string|Array<string>, interpolateParams?: Object)`
Это возвращает наблюдаемый объект. Наблюдаемый объект как таковой является асинхронным, а это гарантирует, что файл перевода будет загружен до использования значения. Этот объект завершается, как только извлечено значение.
Второй метод выглядит так:
instant(key: string|Array<string>, interpolateParams?: Object)`
Это синхронный вариант. Если файл перевода не будет загружен во время использования этого метода, вы вообще не получите перевод.
Помните, ранее мы сказали сервису использовать en в качестве текущего язык? Именно поэтому все результаты перевода изначально будут исходить из en.json.
import { Component } from '@angular/core'; import { TranslateService } from '@ngx-translate/core'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'] }) export class AppComponent { user!: { firstName: string; lastName: string; }; welcome!: string; usernameLabel!: string; passwordLabel!: string; constructor(translate: TranslateService) { translate.addLangs(['en', 'klingon']); translate.setDefaultLang('en'); translate.use('en'); } ngOnInit() { // hardcoded example this.user = { firstName: '8host', lastName: 'Shark' }; // synchronous. Also interpolate the 'firstName' parameter with a value. this.welcome = this.translate.instant('welcomeMessage', { firstName: this.user.firstName }); // asynchronous - gets translations then completes. this.translate.get(['login.username', 'login.password']) .subscribe(translations => { this.usernameLabel = translations['login.username']; this.passwordLabel = translations['login.password']; }); } }
Для переключения между языками в своем приложении вы можете реализовать свой собственный метод — вызовите метод use(lang: string) в TranslateService, чтобы установить текущий язык.
Использование TranslatePipe
Вы можете использовать каналы переводов так же, как и любой другой канал в Angular. Ввод в данном случае — это ключ нужного вам перевода. Дополнительный параметр — это объект, определяющий строки интерполяции, ожидаемые при переводе.
В приведенном ниже примере компонент содержит пользовательский объект со свойством firstName:
<p>{{ 'welcomeMessage' | translate: user }}</p>
Этот код выдаст предложение:
"Thanks for joining, 8host! It's great to have you!"
Это соответствует ожидаемой интерполяции.
<input type="password" placeholder="{{ 'login.password' | translate }}">
Этот код создаст ввод с заполнителем:
"Password here"
Использование TranslateDirective
Чтобы получить перевод, вы также можете поместить директиву в любой элемент HTML.
Есть несколько способов сделать это.
Следующий код создаст метку: “Enter your user name”.
Вы также можете установить ключ перевода в качестве содержимого элемента.
<p translate [translateParams]="{ firstName: user.firstName }">welcomeMessage</p>
Этот код выдаст сообщение:
"Thanks for joining, 8host! It's great to have you!"
Итоги
В этом мануале вы научились использовать плагин ngx-translate в приложении Angular.
Читайте также: Оптимизация размеров пакетов в Angular