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

Оглавление

Что такое Intlayer?

Intlayer — это инновационная библиотека интернационализации (i18n) с открытым исходным кодом, разработанная для упрощения поддержки нескольких языков в современных веб-приложениях.

С помощью Intlayer вы можете:

• Легко управлять переводами, используя декларативные словари на уровне компонентов.
• Динамически локализовать метаданные, маршруты и контент.
• Обеспечить поддержку TypeScript с автоматически сгенерированными типами, улучшая автодополнение и обнаружение ошибок.
• Использовать расширенные возможности, такие как динамическое обнаружение и переключение языка.

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

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

Шаг 1: Установка зависимостей

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

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: Настройка вашего проекта

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

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: Интеграция Intlayer в конфигурацию Angular

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

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

{  "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 в корневом каталоге вашего проекта:

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: Объявите свой контент

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

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

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

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

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

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 внутри любого компонента.

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");}

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

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

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

(Дополнительно) Шаг 6: Изменение языка контента

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

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

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:

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.