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

Зміст

Що таке Intlayer?

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

З Intlayer ви можете:

• Легко керувати перекладами за допомогою декларативних словників на рівні компонентів.
• Динамічно локалізувати метадані, маршрути та вміст.
• Забезпечити підтримку TypeScript за допомогою автогенерованих типів, що покращує автодоповнення та виявлення помилок.
• Скористатися розширеними функціями, такими як динамічне визначення та перемикання мови.

Покроковий посібник з налаштування 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.