Перекладіть ваш вебсайт 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-адреси, редиректи middleware, назви файлів 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.