Переведите ваш сайт на Vite и Vanilla JS с помощью Intlayer | Интернационализация (i18n)

Содержание

Почему Intlayer лучше альтернатив?

По сравнению с основными решениями, такими как i18next или i18n.js, Intlayer — это решение, которое включает в себя встроенные оптимизации, такие как:

Пошаговое руководство по настройке Intlayer в приложении на Vite и Vanilla JS

1. 1

   Установка зависимостей

   Установите необходимые пакеты с помощью npm:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npx intlayer init --interactive
   

   флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

   Эта команда определит вашу среду и установит необходимые пакеты. Например:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install intlayer vanilla-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и команд CLI.

   • vanilla-intlayer Пакет для интеграции Intlayer в приложения на чистом JavaScript / TypeScript. Он предоставляет синглтон pub/sub (IntlayerClient) и вспомогательные функции на основе колбэков (useIntlayer, useLocale и т. д.), чтобы любая часть вашего приложения могла реагировать на изменения языка без зависимости от UI-фреймворка.

   • vite-intlayer Включает плагин Vite для интеграции Intlayer с бандлером Vite, а также посредник (middleware) для определения предпочтительного языка пользователя, управления куки и обработки перенаправления 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, перенаправление посредника, имена куки, местоположение и расширение ваших объявлений контента, отключить логи 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({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

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

4. 4

   Инициализация Intlayer в точке входа

   Вызовите installIntlayer() перед рендерингом любого контента, чтобы глобальный синглтон языка был готов.

   src/main.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { installIntlayer } from "vanilla-intlayer";
   
   // Должно быть вызвано перед рендерингом любого i18n контента.
   installIntlayer();
   
   // Импортируйте и запустите модули вашего приложения.
   import "./app.js";
   

   Если вы также используете объявления контента md() (Markdown), установите также рендерер макрдауна:

   src/main.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";
   
   installIntlayer();
   installIntlayerMarkdown();
   
   import "./app.js";
   

5. 5

   Объявление вашего контента

   Создавайте объявления контента для хранения переводов и управляйте ими:

   src/app.content.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { insert, t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "Vite + Vanilla",
   
       viteLogoLabel: t({
         en: "Vite Logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
   
       count: insert(
         t({
           en: "count is {{count}}",
           fr: "le compte est {{count}}",
           es: "el recuento es {{count}}",
         })
       ),
   
       readTheDocs: t({
         en: "Click on the Vite logo to learn more",
         fr: "Cliquez sur le logo Vite pour en savoir plus",
         es: "Нажмите на логотип Vite, чтобы узнать больше",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   Ваши объявления контента могут быть определены в любом месте вашего приложения, при условии, что они включены в каталог contentDir (по умолчанию ./src) и соответствуют расширению файла объявления контента (по умолчанию .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Дополнительную информацию см. в документации по объявлению контента.

6. 6

   Использование Intlayer в вашем JavaScript

   vanilla-intlayer повторяет поверхностный API react-intlayer: useIntlayer(key, locale?) возвращает переведенный контент напрямую. Добавьте .onChange() к результату, чтобы подписаться на изменения языка - это явный эквивалент ререндеринга в React.

   src/main.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { installIntlayer, useIntlayer } from "vanilla-intlayer";
   
   installIntlayer();
   
   // Получите начальный контент для текущего языка.
   // Добавьте .onChange(), чтобы получать уведомления при смене языка.
   const content = useIntlayer("app").onChange((newContent) => {
     // Перерисуйте или обновите только затронутые узлы DOM
     document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(
       newContent.title
     );
     document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
       String(newContent.readTheDocs);
   });
   
   // Начальный рендеринг
   document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(
     content.title
   );
   document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =
     String(content.readTheDocs);
   

   Обращайтесь к значениям как к строкам, оборачивая их в String(), что вызывает метод toString() узла и возвращает переведенный текст.

   Когда вам нужно значение для стандартного HTML-атрибута (например, alt, aria-label), используйте .value напрямую:

   typescript

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   img.alt = content.viteLogoLabel.value;
   

7. 7

   Изменение языка вашего контента

   Необязательно

   Чтобы изменить язык вашего контента, используйте функцию setLocale, предоставляемую useLocale.

   src/locale-switcher.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { getLocaleName } from "intlayer";
   import { useLocale } from "vanilla-intlayer";
   
   export function setupLocaleSwitcher(container: HTMLElement): () => void {
     const { locale, availableLocales, setLocale, subscribe } = useLocale();
   
     const select = document.createElement("select");
     select.setAttribute("aria-label", "Language");
   
     const render = (currentLocale: string) => {
       select.innerHTML = availableLocales
         .map(
           (loc) =>
             `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>
               ${getLocaleName(loc)}
             </option>`
         )
         .join("");
     };
   
     render(locale);
     container.appendChild(select);
   
     select.addEventListener("change", () => setLocale(select.value as any));
   
     // Синхронизация выпадающего списка при изменении языка из другого места
     return subscribe((newLocale) => render(newLocale));
   }
   

8. 8

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

   Необязательно

   Intlayer поддерживает объявления контента md() и html(). В чистом JS скомпилированный результат вставляется как необработанный HTML через innerHTML.

   Компиляция и вставка HTML:

   src/main.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import {
     compileMarkdown,
     installIntlayerMarkdown,
     useIntlayer,
   } from "vanilla-intlayer";
   
   installIntlayerMarkdown();
   
   const content = useIntlayer("app").onChange((newContent) => {
     const el = document.querySelector<HTMLDivElement>(".edit-note")!;
     el.innerHTML = compileMarkdown(String(newContent.editNote));
   });
   
   document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =
     compileMarkdown(String(content.editNote));
   

   TIP

   String(content.editNote) вызывает toString() для IntlayerNode, который возвращает необработанную строку Markdown. Передайте её в compileMarkdown, чтобы получить HTML-строку, а затем установите через innerHTML.

   WARNING

   Используйте innerHTML только для доверенного контента. Если макрдаун получен из пользовательского ввода, сначала очистите его (например, с помощью DOMPurify). Вы можете динамически установить рендерер с очисткой:

   typescript

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";
   
   await installIntlayerMarkdownDynamic(async () => {
     const DOMPurify = await import("dompurify");
     return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));
   });
   

9. 9

   Добавление локализованной маршрутизации в ваше приложение

   Необязательно

   Чтобы создать уникальные маршруты для каждого языка (полезно для SEO), вы можете использовать intlayerProxy в вашей конфигурации Vite для определения языка на стороне сервера.

   Сначала добавьте intlayerProxy в конфигурацию Vite:

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

   Начиная с Intlayer v9, intlayerProxy() встроен непосредственно в плагин intlayer() и включен по умолчанию через опцию routing.enableProxy (true по умолчанию). Отдельная регистрация, как показано ниже, теперь опциональна — она сохранена для обратной совместимости и для настроек, которым требуется контролировать порядок плагинов. Установите routing.enableProxy: false для отказа. См. заметки выпуска v9.

   vite.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

10. 10

    Изменение URL при смене языка

    Необязательно

    Чтобы обновлять URL браузера при смене языка, вызовите useRewriteURL() после установки Intlayer:

    src/main.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { installIntlayer, useRewriteURL } from "vanilla-intlayer";
    
    installIntlayer();
    
    // Перезаписывает URL немедленно и при каждой последующей смене языка.
    // Возвращает функцию отписки для очистки.
    const stopRewriteURL = useRewriteURL();
    

11. 11

    Переключение атрибутов языка и направления текста HTML

    Необязательно

    Обновляйте атрибуты lang и dir тега <html> в соответствии с текущим языком для обеспечения доступности и SEO.

    src/main.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { getHTMLTextDir } from "intlayer";
    import { installIntlayer, useLocale } from "vanilla-intlayer";
    
    installIntlayer();
    
    useLocale({
      onLocaleChange: (locale) => {
        document.documentElement.lang = locale;
        document.documentElement.dir = getHTMLTextDir(locale);
      },
    });
    

12. 12

    Ленивая загрузка словарей по языкам

    Необязательно

    Для больших приложений вы можете разделить словари по языкам на отдельные чанки. Используйте useDictionaryDynamic вместе с динамическим import() от Vite:

    src/app.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";
    
    installIntlayer();
    
    const unsubscribe = useDictionaryDynamic(
      {
        en: () => import("../.intlayer/dictionaries/en/app.mjs"),
        fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),
        es: () => import("../.intlayer/dictionaries/es/app.mjs"),
      },
      "app"
    ).onChange((content) => {
      document.querySelector("h1")!.textContent = String(content.title);
    });
    

    Бандл каждого языка запрашивается только тогда, когда этот язык становится активным, и результат кэшируется - последующие переключения на тот же язык происходят мгновенно.

13. 13

    Извлечение контента из ваших компонентов

    Необязательно

    Если у вас уже есть кодовая база, преобразование тысяч файлов может занять много времени.

    Чтобы облегчить этот процесс, 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;
    

    Команда ExtractКомпилятор Babel

    Запустите экстрактор, чтобы преобразовать ваши компоненты и извлечь контент

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Обновите vite.config.ts, включив плагин intlayerCompiler:

    vite.config.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npm run build # Или npm run dev
    

(Опционально) 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": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

Настройка Git

Рекомендуется игнорировать файлы, созданные Intlayer. Это позволит не добавлять их в ваш Git-репозиторий.

Для этого добавьте следующие инструкции в ваш файл .gitignore:

# Игнорировать файлы, созданные Intlayer
.intlayer

Расширение для VS Code

Чтобы сделать разработку с Intlayer удобнее, вы можете установить официальное расширение Intlayer для VS Code.

Установить из VS Code Marketplace

Это расширение предоставляет:

• Автодополнение для ключей перевода.
• Обнаружение ошибок в реальном времени для отсутствующих переводов.
• Инлайновые превью переведенного контента.
• Быстрые действия для легкого создания и обновления переводов.

Для получения более подробной информации об использовании расширения см. документацию к расширению Intlayer для VS Code.

Что дальше?

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

Часто задаваемые вопросы