Как использовать ngx-translate в Angular

Development, Java | Amber | Комментировать запись

В какой-то момент вашему веб-приложению может потребоваться многоязычная пользовательская база. Но как ее обслуживать? Интернационализация, или сокращенно 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