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

Оглавление

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

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

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

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

1. 1

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

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

   bash

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

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

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

   npx intlayer init --interactive
   

   флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

   Эта команда определит вашу среду и установит необходимые пакеты. Например:

   bash

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

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

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

   npm install intlayer angular-intlayer
   npm install @angular-builders/custom-esbuild --save-dev
   

   • 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 22).

   Сначала измените ваш 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.

Часто задаваемые вопросы