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

Содержание

Что такое Intlayer?

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

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

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

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

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

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

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

npm install intlayer angular-intlayer vite-intlayernpx intlayer init

• intlayer

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

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

• vite-intlayer Пакет для интеграции Intlayer с Vite. Предоставляет плагин для обработки файлов декларации контента и настраивает алиасы для оптимальной производительности.

Шаг 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, имена куки, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.

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

Для интеграции Intlayer с Analog вам необходимо использовать плагин vite-intlayer.

Измените файл vite.config.ts:

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";import analog from "@analogjs/platform";// https://vitejs.dev/config/export default defineConfig(() => ({  plugins: [    analog(),    intlayer(), // Добавьте плагин Intlayer  ],}));

Плагин intlayer() настраивает Vite для работы с Intlayer. Он обрабатывает файлы декларации контента и устанавливает алиасы для оптимальной производительности.

Шаг 4: Декларация вашего контента

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

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

Для получения более подробной информации см. документацию по декларации контента.

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

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

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

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

import { Component } from "@angular/core";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-home",  standalone: true,  template: `    <div class="content">      <h1>{{ content().title }}</h1>      <p>{{ content().congratulations }}</p>    </div>  `,})export default class HomeComponent {  content = useIntlayer("app");}

Контент 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;}

Затем используйте этот компонент на своих страницах:

import { Component } from "@angular/core";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "../locale-switcher.component";@Component({  selector: "app-home",  standalone: true,  imports: [LocaleSwitcherComponent],  template: `    <app-locale-switcher></app-locale-switcher>    <div class="content">      <h1>{{ content().title }}</h1>      <p>{{ content().congratulations }}</p>    </div>  `,})export default class HomeComponent {  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.