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

Зміст

Що таке Intlayer?

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

З Intlayer ви можете:

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

Покрокова інструкція з налаштування Intlayer у додатку Vite та Lit

Крок 1: Встановлення залежностей

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

npm install intlayer lit-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer

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

• lit-intlayer Пакет, що інтегрує Intlayer з додатками Lit. Він надає хуки на основі ReactiveController (useIntlayer, useLocale тощо), щоб LitElement автоматично перерендерилися при зміні мови.

• vite-intlayer Включає плагін Vite для інтеграції Intlayer з бандлером Vite, а також проміжне програмне забезпечення (middleware) для визначення мови користувача, керування файлами cookie та обробки перенаправлень URL.

Крок 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-адреси, перенаправлення проміжного ПЗ, назви файлів cookie, розташування та розширення ваших декларацій контенту, вимкнути журнали Intlayer у консолі та багато іншого. Повний список доступних параметрів дивіться в документації з конфігурації.

Крок 3: Інтегруйте Intlayer у вашу конфігурацію Vite

Додайте плагін intlayer до вашої конфігурації.

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});

Плагін Vite intlayer() використовується для інтеграції Intlayer з Vite. Він забезпечує створення файлів декларації контенту та відстежує їх у режимі розробки. Він визначає змінні середовища Intlayer у додатку Vite. Крім того, він надає псевдоніми (aliases) для оптимізації продуктивності.

Крок 4: Запустіть Intlayer у вашій точці входу

Викличте installIntlayer() перед реєстрацією будь-яких користувацьких елементів, щоб глобальний синглтон локалі був готовий, коли перший елемент підключиться.

import { installIntlayer } from "lit-intlayer";// Повинно бути викликано до того, як будь-який LitElement підключиться до DOM.installIntlayer();// Імпортуйте та зареєструйте ваші користувацькі елементи.import "./my-element.js";

Якщо ви також використовуєте декларації контенту md() (Markdown), встановіть також рендерер markdown:

import { installIntlayer, installIntlayerMarkdown } from "lit-intlayer";installIntlayer();installIntlayerMarkdown();import "./my-element.js";

Крок 5: Декларуйте ваш контент

Створюйте та керуйте вашими деклараціями контенту для зберігання перекладів:

import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Lit",

    viteLogo: t({
      en: "Vite logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),
    litLogo: t({
      en: "Lit logo",
      fr: "Logo Lit",
      es: "Logo Lit",
    }),

    count: t({
      en: "count is {{count}}",
      fr: "le compte est {{count}}",
      es: "el recuento es {{count}}",
    }),

    readTheDocs: t({
      en: "Click on the Vite and Lit logos to learn more",
      fr: "Cliquez sur les logos Vite et Lit pour en savoir plus",
      es: "Haga clic en los logotipos de Vite y Lit para obtener más información",
    }),
  },
} satisfies Dictionary;

export default appContent;

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

Для отримання додаткової інформації дивіться документацію з декларації контенту.

Крок 6: Використовуйте Intlayer у вашому LitElement

Використовуйте useIntlayer всередині LitElement. Він повертає проксі ReactiveController, який автоматично запускає перерендеринг щоразу, коли змінюється активна мова - додаткових налаштувань не потрібно.

import { LitElement, html } from "lit";import { customElement, property } from "lit/decorators.js";import { useIntlayer } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  @property({ type: Number })  count = 0;  // useIntlayer реєструє себе як ReactiveController.  // Елемент перерендериться автоматично при зміні мови.  private content = useIntlayer(this, "app");  override render() {    const { content } = this;    return html`      <h1>${content.title}</h1>      <img src="/vite.svg" alt=${content.viteLogo.value} />      <img src="/lit.svg" alt=${content.litLogo.value} />      <button @click=${() => this.count++}>        ${content.count({ count: this.count })}      </button>      <p>${content.readTheDocs}</p>    `;  }}

Коли вам потрібен перекладений рядок у нативному атрибуті HTML (наприклад, alt, aria-label, title), викликайте .value на листовому вузлі:

typescript

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

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

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

html`<img alt=${content.viteLogo.value} />`;html`<img alt=${content.viteLogo.toString()} />`;html`<img alt=${String(content.viteLogo)} />`;

(Опціонально) Крок 7: Змініть мову вашого контенту

Щоб змінити мову вашого контенту, скористайтеся методом setLocale, наданим контролером useLocale.

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

(Опціонально) Крок 8: Рендеринг контенту Markdown та HTML

Intlayer підтримує декларації контенту md() та html(). У Lit скомпільований вивід вставляється як сирий HTML за допомогою директиви unsafeHTML.

Відрендерите скомпільований HTML у своєму елементі:

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { unsafeHTML } from "lit/directives/unsafe-html.js";import { useIntlayer } from "lit-intlayer";import { compileMarkdown } from "lit-intlayer/markdown";@customElement("my-element")export class MyElement extends LitElement {  private content = useIntlayer(this, "app");  override render() {    return html`      <div class="edit-note">        ${unsafeHTML(compileMarkdown(String(this.content.editNote)))}      </div>    `;  }}

TIP

String(content.editNote) викликає toString() на IntlayerNode, який повертає сирий рядок Markdown. Передайте його в compileMarkdown, щоб отримати рядок HTML, а потім відрендерите за допомогою директиви unsafeHTML від Lit.

(Опціонально) Крок 9: Додайте локалізовану маршрутизацію до вашого додатка

Для створення унікальних маршрутів для кожної мови (корисно для SEO), ви можете використовувати клієнтський маршрутизатор разом із помічниками Intlayer localeMap / localeFlatMap та плагіном Vite intlayerProxy для визначення мови на стороні сервера.

Спочатку додайте intlayerProxy до вашої конфігурації Vite:

Зверніть увагу, що для використання intlayerProxy у продакшні вам потрібно перемістити vite-intlayer з devDependencies до dependencies.

import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [intlayer(), intlayerProxy()],
});

(Опціонально) Крок 10: Зміна URL при зміні мови

Щоб оновлювати URL-адресу браузера при зміні мови, використовуйте useRewriteURL разом із перемикачем мови:

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale, useRewriteURL } from "lit-intlayer";@customElement("locale-switcher")export class LocaleSwitcher extends LitElement {  private locale = useLocale(this);  // Автоматично перезаписує поточний URL при зміні мови.  private _rewriteURL = useRewriteURL(this);  private _onChange(e: Event) {    const select = e.target as HTMLSelectElement;    this.locale.setLocale(select.value as any);  }  override render() {    return html`      <select @change=${this._onChange}>        ${this.locale.availableLocales.map(          (loc) => html`            <option value=${loc} ?selected=${loc === this.locale.locale}>              ${getLocaleName(loc)}            </option>          `        )}      </select>    `;  }}

(Опціонально) Крок 11: Перемикання атрибутів мови та напрямку HTML

Оновлюйте атрибути lang та dir тегу <html> відповідно до поточної мови для доступності та SEO.

import { LitElement, html } from "lit";import { customElement } from "lit/decorators.js";import { getHTMLTextDir } from "intlayer";import { useLocale } from "lit-intlayer";@customElement("my-element")export class MyElement extends LitElement {  private locale = useLocale(this, {    onLocaleChange: (loc) => {      document.documentElement.lang = loc;      document.documentElement.dir = getHTMLTextDir(loc);    },  });  override render() {    return html`<!-- ваш контент -->`;  }}

(Опціонально) Крок 12: Витягніть контент ваших компонентів

Якщо у вас є існуюча кодова база, трансформація тисяч файлів може зайняти багато часу.

Щоб полегшити цей процес, Intlayer пропонує компілятор / екстрактор для трансформації ваших компонентів та витягування контенту.

Щоб налаштувати це, ви можете додати розділ compiler у ваш файл intlayer.config.ts:

import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... решта вашої конфігурації  compiler: {    /**     * Вказує, чи має бути увімкнено компілятор.     */    enabled: true,    /**     * Визначає шлях файлів виводу     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Вказує, чи мають компоненти бути збережені після трансформації.     * Таким чином, компілятор можна запустити лише один раз для трансформації додатка, а потім його можна видалити.     */    saveComponents: false,    /**     * Префікс ключа словника     */    dictionaryKeyPrefix: "",  },};export default config;

(Опційно) Sitemap і robots.txt (генерація під час збірки)

Intlayer надає generateSitemap і getMultilingualUrls - утиліти для формування багатомовних sitemap.xml і robots.txt для краулерів та автоматичного запису в public/. Зазвичай запускають невеликий Node-скрипт перед Vite (наприклад, npm-хуки predev / prebuild).

Sitemap

Генератор sitemap враховує локалі й додає метадані для краулерів.

Підтримується простір імен xhtml:link (hreflang). Замість плоского списку URL Intlayer пов’язує всі мовні версії сторінки в обидва боки (наприклад /about, /fr/about або /about?lang=fr залежно від режиму маршрутизації).

Robots.txt

Використовуйте getMultilingualUrls, щоб правила Disallow покривали всі локалізовані варіанти шляхів.

1. Файл generate-seo.mjs у корені проєкту

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Пакет intlayer має бути встановлений. У продакшені задайте SITE_URL у середовищі (наприклад у CI).

Для Node ESM краще generate-seo.mjs. Для generate-seo.js додайте "type": "module" у package.json або ввімкніть ESM інакше.

2. Запуск скрипта перед Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Підлаштуйте команди для pnpm або yarn. Можна викликати скрипт із CI.

Конфігурація TypeScript

Переконайтеся, що ваша конфігурація TypeScript включає автоматично згенеровані типи.

{  "compilerOptions": {    // ...    "experimentalDecorators": true,    "useDefineForClassFields": false,  },  "include": ["src", ".intlayer/**/*.ts"],}

experimentalDecorators та useDefineForClassFields: false потрібні для Lit для підтримки декораторів.

Конфігурація Git

Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволяє уникнути їхнього коміту до вашого репозиторію Git.

Для цього ви можете додати наступні інструкції до вашого файлу .gitignore:

# Ігнорувати файли, згенеровані Intlayer.intlayer

Розширення VS Code

Щоб покращити ваш досвід розробки з Intlayer, ви можете встановити офіційне розширення Intlayer для VS Code.

Встановити з VS Code Marketplace

Це розширення надає:

• Автодоповнення для ключів перекладів.
• Виявлення помилок у реальному часі для відсутніх перекладів.
• Вбудований попередній перегляд перекладеного контенту.
• Швидкі дії для легкого створення та оновлення перекладів.

Докладніше про використання розширення дивіться в документації до розширення Intlayer для VS Code.

Йдіть далі

Щоб дізнатися більше, ви можете впровадити візуальний редактор або винести ваш контент у зовнішню систему за допомогою CMS.