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

Содержание

Что такое Intlayer?

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

С Intlayer вы можете:

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

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

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

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

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

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

• intlayer

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

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

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

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

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

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

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

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

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

Шаг 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.