Creation:2025-04-18Last update:2026-05-31

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

    www.youtube.com

    Table of Contents

    Цей пакет знаходиться в розробці. Див. issue для отримання додаткової інформації. Підтримайте зацікавленість до Intlayer для Solid, поставивши лайк цьому issue

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

    Порівняно з основними рішеннями, такими як @solid-primitives/i18n або i18next, Intlayer — це рішення, яке постачається з інтегрованою оптимізацією, як-от:

    Intlayer оптимізовано для ідеальної роботи з Solid, пропонуючи визначення вмісту на рівні компонентів, реактивні переклади та всі функції, необхідні для масштабування інтернаціоналізації (i18n).

    Замість того, щоб завантажувати великі файли JSON на свої сторінки, завантажуйте лише необхідний вміст. Intlayer допомагає зменшити розмір бандлу і сторінок до 50%.

    Організація вмісту за окремими областями (scoping) полегшує технічне обслуговування великомасштабних програм. Ви можете скопіювати або видалити окрему папку функцій без розумового навантаження перегляду всієї кодової бази вмісту. Крім того, Intlayer повністю типізований (fully typed), щоб забезпечити точність вашого вмісту.

    Спільне розміщення вмісту зменшує контекст, необхідний для великих мовних моделей (LLM). Intlayer також постачається з набором інструментів, наприклад CLI для перевірки відсутніх перекладів,LSP, MCP і навички агента, щоб зробити роботу розробника (DX) ще зручнішою для агентів ШІ.

    Використовуйте автоматизацію для перекладу в конвеєрі CI/CD за допомогою LLM за вашим вибором за рахунок вашого постачальника штучного інтелекту. Intlayer також пропонує компілятор для автоматизації екстракція вмісту, а також веб-платформу, щоб допомогти перекладати у фоновому режимі.

    Підключення великих файлів JSON до компонентів може призвести до проблем з продуктивністю та реакцією. Intlayer оптимізує завантаження вмісту під час збірки (build time).

    Більше ніж просто рішення i18n, Intlayer пропонує власний візуальний редактор і повний CMS, щоб допомогти вам керувати своїм багатомовним вмістом у реальному часі, спрощуючи співпрацю з перекладачами, копірайтерами та іншими членами команди. Контент можна зберігати локально та/або віддалено.

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

    Зміст

    1. Встановіть залежності

      Встановіть необхідні пакети, використовуючи npm:

      bash
      npm install intlayer solid-intlayernpm install vite-intlayer --save-devnpx intlayer init

      • intlayer

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

      • solid-intlayer Пакет, що інтегрує Intlayer з додатком на Solid. Надає провайдери контексту та хуки для інтернаціоналізації в Solid.

      • vite-intlayer Містить плагін для Vite для інтеграції Intlayer зі збірником Vite, а також middleware для визначення пріоритетної локалі користувача, керування cookies та обробки перенаправлень URL.

    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. Інтеграція Intlayer у вашу конфігурацію Vite

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

      vite.config.ts
      import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";

// Документація: https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), intlayer()],
});
      Плагін Vite intlayer() використовується для інтеграції Intlayer з Vite. Він забезпечує побудову файлів декларацій вмісту та відстежує їх у режимі розробки. Він визначає змінні оточення Intlayer у застосунку Vite. Додатково він надає aliases для оптимізації продуктивності.

    4. Оголосіть свій вміст

      Створіть і керуйте деклараціями вмісту, щоб зберігати переклади:

      src/app.content.tsx
      import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {},
} satisfies Dictionary;

export default appContent;
      Ваші декларації контенту можуть бути визначені будь-де у вашому застосунку, щойно вони будуть включені до директорії contentDir (за замовчуванням, ./src). І відповідати розширенню файлів декларацій контенту (за замовчуванням, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Для детальнішої інформації зверніться до документації щодо декларації контенту.

    5. Використання Intlayer у вашому коді

      Отримайте доступ до ваших словників контенту в усьому додатку:

      src/App.tsx
      import { createSignal, type Component } from "solid-js";import solidLogo from "./assets/solid.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "solid-intlayer";const AppContent: Component = () => {  const [count, setCount] = createSignal(0);  const content = useIntlayer("app");  return (    <>      <div>        <a href="https://vitejs.dev" target="_blank">          <img src={viteLogo} class="logo" alt={content.viteLogo.value} />        </a>        <a href="https://www.solidjs.com/" target="_blank">          <img            src={solidLogo}            class="logo solid"            alt={content.solidLogo.value}          />        </a>      </div>      <h1>{content.title}</h1>      <div class="card">        <button onClick={() => setCount((count) => count + 1)}>          {content.count({ count: count() })}        </button>        <p>{content.edit}</p>      </div>      <p class="read-the-docs">{content.readTheDocs}</p>    </>  );};const App: Component = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;
      У Solid, useIntlayer повертає функцію accessor (наприклад, `content.). Ви повинні викликати цю функцію для доступу до реактивного контенту.

      Якщо ви хочете використовувати ваш контент у атрибуті string, такому як alt, title, href, aria-label тощо, ви повинні викликати значення функції, як:

      html
      <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

    6. Змінити мову вашого контенту

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

      Щоб змінити мову вашого контенту, ви можете використовувати функцію setLocale, надану хуком useLocale. Ця функція дозволяє вам встановити locale додатку та оновити контент відповідно.

      src/components/LocaleSwitcher.tsx
      import { type Component, For } from "solid-js";import { Locales } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const { locale, setLocale, availableLocales } = useLocale();  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as Locales)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

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

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

      Мета цього кроку - створити унікальні маршрути для кожної мови. Це корисно для SEO та SEO-дружніх URL. Приклад:

      plaintext
      - https://example.com/about- https://example.com/es/about- https://example.com/fr/about

      Щоб додати локалізовану маршрутизацію до вашого додатку, ви можете використовувати @solidjs/router.

      Спочатку встановіть необхідні залежності:

      bash
      npm install @solidjs/router

      Потім обгорніть ваш додаток у Router та визначте ваші маршрути, використовуючи localeMap:

      src/index.tsx
      import { render } from "solid-js/web";import { Router } from "@solidjs/router";import App from "./App";const root = document.getElementById("root");render(  () => (    <Router>      <App />    </Router>  ),  root!);
      src/App.tsx
      import { type Component } from "solid-js";import { Route } from "@solidjs/router";import { localeMap } from "intlayer";import { IntlayerProvider } from "solid-intlayer";import Home from "./pages/Home";import About from "./pages/About";const App: Component = () => (  <IntlayerProvider>    {localeMap(({ locale, urlPrefix }) => (      <Route        path={urlPrefix || "/"}        component={(props: any) => (          <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>        )}      >        <Route path="/" component={Home} />        <Route path="/about" component={About} />      </Route>    ))}  </IntlayerProvider>);export default App;

    8. Змінити URL при зміні locale

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

      Щоб змінити URL при зміні locale, ви можете використовувати prop onLocaleChange, наданий хуком useLocale. Ви можете використовувати хуки useNavigate та useLocation з @solidjs/router для оновлення шляху URL.

      src/components/LocaleSwitcher.tsx
      import { type Component, For } from "solid-js";import { useLocation, useNavigate } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const location = useLocation();  const navigate = useNavigate();  const { locale, setLocale, availableLocales } = useLocale({    onLocaleChange: (loc) => {      const pathWithLocale = getLocalizedUrl(location.pathname, loc);      navigate(pathWithLocale);    },  });  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as any)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

    9. Переключити атрибути мови та напрямку HTML

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

      Оновіть атрибути lang та dir тега <html>, щоб вони відповідали поточному locale для доступності та SEO.

      src/App.tsx
      import { createEffect, type Component } from "solid-js";import { useLocale } from "solid-intlayer";import { getHTMLTextDir } from "intlayer";const AppContent: Component = () => {  const { locale } = useLocale();  createEffect(() => {    document.documentElement.lang = locale();    document.documentElement.dir = getHTMLTextDir(locale());  });  return (    // ... Контент вашого додатку  );};

    10. Створення локалізованого компонента посилання

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

      Створіть користувацький компонент Link, який автоматично додає префікс внутрішніх URL поточною мовою.

      src/components/Link.tsx
      import { type ParentComponent } from "solid-js";import { A, type AnchorProps } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";export const Link: ParentComponent<AnchorProps> = (props) => {  const { locale } = useLocale();  const isExternal = () => props.href.startsWith("http");  const localizedHref = () =>    isExternal() ? props.href : getLocalizedUrl(props.href, locale());  return <A {...props} href={localizedHref()} />;};

    11. Рендеринг Markdown

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

      Intlayer підтримує рендеринг контенту Markdown безпосередньо у вашому додатку Solid, використовуючи власний внутрішній парсер. За замовчуванням Markdown обробляється як звичайний текст. Щоб відрендерити його як багатий HTML, обгорніть ваш додаток у MarkdownProvider.

      src/index.tsx
      import { render } from "solid-js/web";import { MarkdownProvider } from "solid-intlayer/markdown";import App from "./App";const root = document.getElementById("root");render(  () => (    <MarkdownProvider>      <App />    </MarkdownProvider>  ),  root!);

      Потім ви можете використовувати його у ваших компонентах:

      tsx
      import { useIntlayer } from "solid-intlayer";const MyComponent = () => {  const content = useIntlayer("my-content");  return (    <div>      {/* Рендериться як HTML через MarkdownProvider */}      {content.markdownContent}    </div>  );};

    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;

      Запустіть екстрактор для перетворення компонентів і витягування вмісту

      bash
      npx intlayer extract

    Налаштування TypeScript

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

    tsconfig.json
    {  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

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

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

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

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

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

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

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

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

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

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

    (Опційно) 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 у корені проєкту

    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

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

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

    Розширені можливості

    Щоб піти далі, ви можете реалізувати visual editor або винести свій вміст, використовуючи CMS.

    Nuxt та Vue
    Vite та Svelte