Перекладіть ваш вебсайт Angular 21 (Vite) за допомогою Intlayer | Інтернаціоналізація (i18n)

Зміст

Чому варто обрати Intlayer, а не альтернативи?

Порівняно з основними рішеннями, такими як ngx-translate або angular-l10n, Intlayer — це рішення, яке має такі інтегровані оптимізації, як:

Покроковий посібник із налаштування Intlayer у додатку Angular

Перегляньте Шаблон Додатку на GitHub.

1. 1

   Встановлення залежностей

   Встановіть необхідні пакети за допомогою npm:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   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. 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, вам потрібно використовувати кастомний збирач. У цьому посібнику передбачається, що ви використовуєте Vite/esbuild (за замовчуванням для проєктів Angular 21).

   Спершу змініть ваш 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.