Переведите ваш веб-сайт на Angular 21 (Vite) с помощью Intlayer | Интернационализация (i18n)

Оглавление

Почему Intlayer лучше альтернатив?

По сравнению с основными решениями, такими как ngx-translate или angular-l10n, Intlayer — это решение со встроенными оптимизациями, такими как:

Пошаговое руководство по настройке Intlayer в приложении Angular

Смотрите Шаблон Приложения на GitHub.

1. 1

   Установка зависимостей

   Установите необходимые пакеты с помощью npm:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx intlayer init

   • intlayer

     Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.

   • angular-intlayer Пакет, который интегрирует Intlayer с приложением Angular. Он предоставляет контекстные провайдеры и хуки для интернационализации Angular.

   • @angular-builders/custom-esbuild Необходим для настройки конфигурации esbuild в Angular CLI.

2. 2

   Настройка вашего проекта

   Создайте конфигурационный файл для настройки языков вашего приложения:

   intlayer.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Другие языки
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Через этот конфигурационный файл вы можете настроить локализованные URL, редиректы, названия cookie, расположение и расширение файлов ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.

3. 3

   Интеграция Intlayer в конфигурацию Angular

   Чтобы интегрировать Intlayer с Angular CLI, вам необходимо использовать кастомный сборщик. В этом руководстве предполагается, что вы используете Vite/esbuild (по умолчанию для проектов Angular 21).

   Сначала измените ваш angular.json для использования пользовательского esbuild. Обновите конфигурации build и serve:

   angular.json

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   {  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"          "options": {            "define": {              "process.env": "{}",            },            "plugins": ["./esbuild.plugins.ts"],            "browser": "src/main.ts",            // ...          },        },        "serve": {          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"          "options": {            "prebundle": {              "exclude": [                "intlayer",                "angular-intlayer",                "@intlayer/config/built",                "@intlayer/core"              ]          },        },      },    },  },}

   Не забудьте заменить your-app-name на фактическое название вашего проекта в angular.json.

   Далее создайте файл esbuild.plugins.ts в корневом каталоге вашего проекта:

   esbuild.plugins.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

   Функция intlayerEsbuildPlugin конфигурирует esbuild с Intlayer. Она внедряет плагин для обработки файлов деклараций контента и устанавливает настройки для достижения максимальной производительности.

   Пользователи NX: Сборщики Angular в NX загружают файлы плагинов через собственное разрешение ESM в Node и не компилируют файлы плагинов TypeScript на лету. Используйте вместо этого файл .mjs и соответствующим образом обновите ссылку plugins в angular.json:

   esbuild.plugins.mjs

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

   Затем в angular.json укажите "./esbuild.plugins.mjs" вместо "./esbuild.plugins.ts".

4. 4

   Объявите свой контент

   Создавайте и управляйте декларациями вашего контента для хранения переводов:

   Ваши декларации контента могут быть определены в любом месте вашего приложения, при условии, что они находятся в каталоге contentDir (по умолчанию ./src). А также они должны соответствовать расширению файлов для деклараций контента (по умолчанию .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Подробнее см. в документации по декларации контента.

5. 5

   Использование Intlayer в вашем коде

   Чтобы использовать функции интернационализации Intlayer во всем вашем приложении Angular, вам необходимо предоставить Intlayer в конфигурации приложения.

   src/app/app.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { ApplicationConfig } from "@angular/core";import { provideRouter } from "@angular/router";import { provideIntlayer } from "angular-intlayer";import { routes } from "./app.routes";export const appConfig: ApplicationConfig = {  providers: [    provideRouter(routes),    provideIntlayer(), // Добавьте провайдер Intlayer здесь  ],};

   После этого вы можете использовать функцию useIntlayer внутри любого компонента.

   src/app/app.component.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

   А в вашем шаблоне:

   src/app/app.component.html

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   <div class="content">  <h1>{{ content().title }}</h1>  <p>{{ content().congratulations }}</p></div>

   Контент Intlayer возвращается как сигнал (Signal), поэтому вы обращаетесь к значениям, вызывая сигнал: content().title.

6. 6

   Изменение языка контента

   Необязательно

   Чтобы изменить язык контента, вы можете использовать функцию setLocale, предоставляемую функцией useLocale. Это позволяет устанавливать локаль приложения и соответствующим образом обновлять контент.

   Создайте компонент для переключения между языками:

   src/app/locale-switcher.component.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { useLocale } from "angular-intlayer";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule],  template: `    <div class="locale-switcher">      <select        [value]="locale()"        (change)="setLocale($any($event.target).value)"      >        @for (loc of availableLocales; track loc) {          <option [value]="loc">{{ loc }}</option>        }      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeCtx = useLocale();  locale = this.localeCtx.locale;  availableLocales = this.localeCtx.availableLocales;  setLocale = this.localeCtx.setLocale;}

   Затем используйте этот компонент в app.component.ts:

   src/app/app.component.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "./locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet, LocaleSwitcherComponent],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Настройка TypeScript

Intlayer использует расширение модулей (Module Augmentation) для использования преимуществ TypeScript и создания более надежной кодовой базы.

Убедитесь, что ваша конфигурация TypeScript включает автосгенерированные типы.

{  // ... Ваши существующие конфигурации TypeScript  "include": [    // ... Ваши существующие конфигурации TypeScript    ".intlayer/**/*.ts", // Включить автосгенерированные типы  ],}

Конфигурация Git

Рекомендуется игнорировать файлы, сгенерированные Intlayer. Это позволит вам не коммитить их в ваш Git-репозиторий.

Для этого вы можете добавить следующие инструкции в файл .gitignore:

# Игнорировать файлы, созданные Intlayer.intlayer

Расширение для VS Code

Чтобы улучшить процесс разработки с Intlayer, вы можете установить официальное Расширение Intlayer для VS Code.

Установите из VS Code Marketplace

Это расширение предоставляет:

• Автодополнение для ключей перевода.
• Обнаружение ошибок в реальном времени для недостающих переводов.
• Встроенный предварительный просмотр переведенного контента.
• Быстрые действия для удобного создания и обновления переводов.

Подробнее о том, как использовать расширение, см. в документации к расширению Intlayer для VS Code.

Идти дальше

Чтобы пойти дальше, вы можете реализовать визуальный редактор или экстернализовать свой контент с помощью CMS.