Переведите ваш Angular 19 (Webpack)-сайт с помощью 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-webpack --save-dev
   

   • intlayer

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

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

   • @angular-builders/custom-webpack Требуется для настройки конфигурации Webpack в 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, перенаправление middleware, имена файлов cookie, местоположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.

3. 3

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

   Чтобы интегрировать Intlayer с Angular CLI, вам необходимо использовать пользовательский билдер. Это руководство предполагает, что вы используете Webpack (стандарт для многих проектов Angular).

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

   angular.json

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

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

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

   {
     "projects": {
       "your-app-name": {
         "architect": {
           "build": {
             "builder": "@angular-builders/custom-webpack:browser", // replace "@angular-devkit/build-angular:application",
             "options": {
               "customWebpackConfig": {
                 "path": "./webpack.config.ts",
                 "mergeStrategies": { "module.rules": "prepend" },
               },
               "main": "src/main.ts", // replace "browser": "src/main.ts",
               // ...
             },
           },
           "serve": {
             "builder": "@angular-builders/custom-webpack:dev-server",
           },
         },
       },
     },
   }
   

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

   Затем создайте файл webpack.config.ts в корне вашего проекта:

   webpack.config.ts

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

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

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

   import { mergeConfig } from "angular-intlayer/webpack";
   
   export default mergeConfig({});
   

   Функция mergeConfig настраивает Webpack с использованием Intlayer. Она внедряет IntlayerPlugin (для обработки файлов декларации контента) и настраивает псевдонимы для оптимальной производительности.

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.

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