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

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

    ide.intlayer.org

    Зміст

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

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

    Intlayer оптимізовано для ідеальної роботи зі Svelte, пропонуючи визначення вмісту на рівні компонентів, реактивні переклади та всі функції, необхідні для масштабування інтернаціоналізації (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 та Svelte додаток

    ide.intlayer.org

    Перегляньте Application Template на GitHub.

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

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

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

      • intlayer

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

      • svelte-intlayer Пакет, який інтегрує Intlayer у Svelte-додаток. Він надає провайдери контексту та хуки для інтернаціоналізації у Svelte.

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

    2. Конфігурація вашого проєкту

      Створіть конфігураційний файл для налаштування мов вашого застосунку:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Your other locales    ],    defaultLocale: Locales.ENGLISH,  },};export default config;
      Через цей конфігураційний файл ви можете налаштувати локалізовані URL-адреси, перенаправлення в middleware, назви cookie, розташування та розширення ваших декларацій контенту, вимкнути логи Intlayer у консолі та інше. Для повного списку доступних параметрів зверніться до документації з конфігурації.

    3. Інтеграція Intlayer у конфігурацію Vite

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

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

    4. Оголосіть свій контент

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

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

const appContent = {
  key: "app",
  content: {
    title: t({
      uk: "Привіт, світ",
      en: "Hello World",
      fr: "Bonjour le monde",
      es: "Hola mundo",
    }),
  },
} satisfies Dictionary;

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

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

      src/App.svelte
      <script>  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("app");</script><div><!-- Відобразити вміст як простий контент --><h1>{$content.title}</h1><!-- Зробити вміст редагованим за допомогою редактора --><h1>{@const Title = $content.title}<Title /></h1><!-- Відобразити вміст як рядок --><div aria-label={$content.title.value}></div><div aria-label={$content.title.toString()}></div><div aria-label={String($content.title)}></div>> Якщо ваш застосунок уже існує, ви можете скористатися [Intlayer Compiler](/uk/doc/compiler) у поєднанні з [командой extract](/uk/doc/concept/cli/extract), щоб перетворити тисячі компонентів за одну секунду.

    6. Змініть мову вашого вмісту

      Необов'язково
      src/App.svelte
      <script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from "svelte-intlayer";// Отримати інформацію про локаль та функцію setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Обробка зміни локаліconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  setLocale(newLocale);};</script><div>  <select value={$locale} on:change={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

    7. Відображення Markdown

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

      Intlayer підтримує рендеринг вмісту в Markdown безпосередньо у вашому Svelte-застосунку. За замовчуванням Markdown розглядається як звичайний текст. Щоб перетворити Markdown у багате HTML-представлення, ви можете інтегрувати @humanspeak/svelte-markdown або інший Markdown-парсер.

      Щоб дізнатися, як оголосити markdown-контент за допомогою пакета intlayer, див. документацію з markdown.
      src/App.svelte
      <script>  import { setIntlayerMarkdown } from "svelte-intlayer";  setIntlayerMarkdown((markdown) =>   // відобразити вміст markdown як рядок   return markdown;  );</script><h1>{$content.markdownContent}</h1>
      Ви також можете отримати доступ до даних front-matter вашого markdown за допомогою властивості content.markdownContent.metadata.xxx.

    8. Налаштування intlayer editor / CMS

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

      Щоб налаштувати intlayer editor, дотримуйтесь документації intlayer editor.

      Щоб налаштувати intlayer CMS, дотримуйтесь документації intlayer CMS.

    9. Додайте локалізований Routing у ваш застосунок

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

      Щоб обробляти локалізовану маршрутизацію в Svelte-застосунку, ви можете використовувати svelte-spa-router разом з localeFlatMap від Intlayer для генерації маршрутів для кожної локалі.

      Спочатку встановіть svelte-spa-router:

      bash
      npm install svelte-spa-routernpx intlayer init

      Then, create a Router.svelte file to define your routes:

      src/Router.svelte
      <script lang="ts">import { localeFlatMap } from "intlayer";import Router from "svelte-spa-router";import { wrap } from "svelte-spa-router/wrap";import App from "./App.svelte";const routes = Object.fromEntries(    localeFlatMap(({locale, urlPrefix}) => [    [        urlPrefix || '/',        wrap({            component: App as any,            props: {                locale,            },        }),    ],    ]));</script><Router {routes} />

      Update your main.ts to mount the Router component instead of App:

      src/main.ts
      import { mount } from "svelte";import Router from "./Router.svelte";const app = mount(Router, {  target: document.getElementById("app")!,});export default app;

      Нарешті, оновіть ваш App.svelte, щоб приймати проп locale і використовувати його з useIntlayer:

      src/App.svelte
      <script lang="ts">import type { Locale } from 'intlayer';import { useIntlayer } from "svelte-intlayer";import Counter from './lib/Counter.svelte';import LocaleSwitcher from './lib/LocaleSwitcher.svelte';export let locale: Locale;$: content = useIntlayer('app', locale);</script><main>  <div class="locale-switcher-container">    <LocaleSwitcher currentLocale={locale} />  </div>  <!-- ... решта вашого додатка ... --></main>

      Налаштування маршрутизації на стороні сервера (необов'язково)

      Паралельно ви також можете використати intlayerProxy для додавання маршрутизації на стороні сервера до вашого застосунку. Цей плагін автоматично визначатиме поточну локаль на основі URL і встановлюватиме відповідний cookie для локалі. Якщо локаль не вказана, плагін обере найвідповіднішу локаль на основі налаштувань мови браузера користувача. Якщо локаль не буде виявлена, плагін виконає перенаправлення на локаль за замовчуванням.

      Зауважте, що для використання intlayerProxy в production потрібно перемістити пакет vite-intlayer з devDependencies до dependencies.
      vite.config.ts
      import { defineConfig } from "vite";
import { svelte } from "@sveltejs/vite-plugin-svelte";
import { intlayer, intlayerProxy } from "vite-intlayer";

// https://vitejs.dev/config/ - конфігурація Vite
export default defineConfig({
  plugins: [
    intlayerProxy(), // should be placed first
    svelte(),
    intlayer(),
  ],
});

    10. Зміна URL при зміні локалі

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

      Щоб дозволити користувачам змінювати мову й відповідно оновлювати URL, ви можете створити компонент LocaleSwitcher. Цей компонент використовуватиме getLocalizedUrl з intlayer та push із svelte-spa-router.

      src/lib/LocaleSwitcher.svelte
      <script lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";import { push } from "svelte-spa-router";export let currentLocale: string | undefined = undefined;// Отримати інформацію про локальconst { locale, availableLocales } = useLocale();// Обробка зміни локаліconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  const currentUrl = window.location.pathname;  const url = getLocalizedUrl( currentUrl, newLocale);  push(url);};</script><div class="locale-switcher">  <select value={currentLocale ?? $locale} onchange={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

    11. Інтернаціоналізовані посилання

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

      Для SEO рекомендується додавати префікс локалі до ваших маршрутів (наприклад, /about, /fr/about).

      src/lib/components/Link.svelte
      <script lang="ts">  import { getLocalizedUrl } from "intlayer";  import { useLocale } from "svelte-intlayer";  export let href = "";  const { locale } = useLocale();  // Helper to prefix URL  $: localizedHref = getLocalizedUrl(href, $locale);</script><a href={localizedHref}>  <slot /></a>

    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

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

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

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

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

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

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

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

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

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

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

    (Опційно) 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.

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

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

    Vite та Solid
    SvelteKit