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

Зміст

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

Порівняно з основними рішеннями, такими як lit-localize або i18next, Intlayer — це рішення, яке має такі інтегровані оптимізації, як:

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

1. 1

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

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

   bash

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

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

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

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

3. 3

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

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

   vite.config.ts

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

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

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

   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. 4

   Запустіть Intlayer у вашій точці входу

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

   src/main.ts

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

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

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

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

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

   src/main.ts

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

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

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

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

5. 5

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

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

   src/app.content.ts

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

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

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

   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,md,mdx,yaml,yml}).

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

6. 6

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

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

   src/my-element.ts

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

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

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

   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. 7

   Змініть мову вашого контенту

   Необов'язково

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

   src/locale-switcher.ts

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

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

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

   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. 8

   Рендеринг контенту Markdown та HTML

   Необов'язково

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

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

   src/my-element.ts

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

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

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

   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. 9

   Додайте локалізовану маршрутизацію до вашого додатка

   Необов'язково

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

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

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

   vite.config.ts

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

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

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

   import { defineConfig } from "vite";
   import { intlayer, intlayerProxy } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [intlayer(), intlayerProxy()],
   });

10. 10

    Зміна URL при зміні мови

    Необов'язково

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

    src/locale-switcher.ts

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

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

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

    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. 11

    Перемикання атрибутів мови та напрямку HTML

    Необов'язково

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

    src/my-element.ts

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

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

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

    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. 12

    Витягніть контент ваших компонентів

    Необов'язково

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

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

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

    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.