Creation:2025-11-20Last update:2026-05-31

    Перекладіть свій сайт на SvelteKit із Intlayer | Інтернаціоналізація (i18n)

    ide.intlayer.org

    Зміст

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

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

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

    Див. Шаблон застосунку на GitHub.

    Щоб почати, створіть новий проєкт SvelteKit. Ось кінцева структура, яку ми створимо:

    bash
    .├── intlayer.config.ts├── package.json├── src│   ├── app.d.ts│   ├── app.html│   ├── hooks.server.ts│   ├── lib│   │   ├── getLocale.ts│   │   ├── LocaleSwitcher.svelte│   │   └── LocalizedLink.svelte│   ├── params│   │   └── locale.ts│   └── routes│       ├── [[locale=locale]]│       │   ├── +layout.svelte│       │   ├── +layout.ts│       │   ├── +page.svelte│       │   ├── +page.ts│       │   ├── about│       │   │   ├── +page.svelte│       │   │   ├── +page.ts│       │   │   └── page.content.ts│       │   ├── Counter.content.ts│       │   ├── Counter.svelte│       │   ├── Header.content.ts│       │   ├── Header.svelte│       │   ├── home.content.ts│       │   └── layout.content.ts│       ├── +layout.svelte│       └── layout.css├── static│   ├── favicon.svg│   └── robots.txt├── svelte.config.js├── tsconfig.json└── vite.config.ts

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

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

      bash
      npm install intlayer svelte-intlayernpm install vite-intlayer --save-devnpx intlayer init
      • intlayer: Основний пакет i18n.
      • svelte-intlayer: Надає провайдери контексту та stores для Svelte/SvelteKit.
      • vite-intlayer: Плагін Vite для інтеграції декларацій контенту в процес збірки.

    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;

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

      Оновіть ваш vite.config.ts, щоб додати плагін Intlayer. Цей плагін обробляє транспіляцію ваших файлів вмісту.

      vite.config.ts
      import { sveltekit } from "@sveltejs/kit/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer(), sveltekit()], // порядок важливий: Intlayer має стояти перед SvelteKit});

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

      Створюйте файли декларацій контенту в будь-якому місці вашої папки src (наприклад, src/lib/content або поруч із компонентами). Ці файли визначають перекладний контент для вашого застосунку, використовуючи функцію t() для кожної локалі.

    5. Використання Intlayer у ваших компонентах

      Тепер ви можете використовувати функцію useIntlayer у будь-якому Svelte-компоненті. Вона повертає реактивний store, який автоматично оновлюється при зміні локалі. Функція автоматично враховує поточну локаль (як під час SSR, так і під час навігації на боці клієнта).

      Примітка: useIntlayer повертає Svelte-store, тому потрібно використовувати префікс $ для доступу до його реактивного значення (наприклад, $content.title).
      src/lib/components/Component.svelte
      <script lang="ts">  import { useIntlayer } from "svelte-intlayer";  // "hero-section" відповідає ключу, визначеному в кроці 4  const content = useIntlayer("hero-section");</script><!-- Відобразити контент у простому вигляді --><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>

    6. Налаштування маршрутизації

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

      Нижче наведено кроки для налаштування маршрутизації на основі локалі в SvelteKit. Це дозволяє додавати префікс локалі до ваших URL (наприклад, /en/about, /fr/about) для кращого SEO та зручності користувача.

      bash
      .└─── src    ├── app.d.ts                  # Визначте тип локалі    ├── hooks.server.ts           # Керує маршрутизацією локалей    ├── lib    │   └── getLocale.ts          # Перевіряє локаль у заголовках та cookie    ├── params    │   └── locale.ts             # Визначає параметр локалі    └── routes        ├── [[locale=locale]]     # Обгорнути в групу маршрутів для встановлення локалі        │   ├── +layout.svelte    # Локальний layout для маршруту        │   ├── +layout.ts        │   ├── +page.svelte        │   ├── +page.ts        │   └── about        │       ├── +page.svelte        │       └── +page.ts        └── +layout.svelte         # Root layout для шрифтів і глобальних стилів

    7. Обробка визначення локалі на сервері

      У SvelteKit сервер повинен знати локаль користувача, щоб відрендерити правильний вміст під час SSR. Ми використовуємо hooks.server.ts для виявлення локалі з URL або cookies.

      Створіть або змініть src/hooks.server.ts:

      src/hooks.server.ts
      import type { Handle } from "@sveltejs/kit";import { getLocalizedUrl } from "intlayer";import { getLocale } from "$lib/getLocale";export const handle: Handle = async ({ event, resolve }) => {  const detectedLocale = getLocale(event);  // Перевіряємо, чи поточний шлях вже починається з локалі (наприклад, /fr, /en)  const pathname = event.url.pathname;  const targetPathname = getLocalizedUrl(pathname, detectedLocale);  // Якщо в URL немає локалі (наприклад, користувач відвідує "/"), перенаправляємо його  if (targetPathname !== pathname) {    return new Response(undefined, {      headers: { Location: targetPathname },      status: 307, // Тимчасове перенаправлення    });  }  return resolve(event, {    transformPageChunk: ({ html }) => html.replace("%lang%", detectedLocale),  });};

      Потім створіть допоміжну функцію для отримання локалі користувача з події запиту:

      src/lib/getLocale.ts
      import {  configuration,  getLocaleFromStorage,  localeDetector,  type Locale,} from "intlayer";import type { RequestEvent } from "@sveltejs/kit";/** * Отримати локаль користувача з події запиту. * Ця функція використовується в хуку `handle` у `src/hooks.server.ts`. * * Спочатку вона намагається отримати локаль із сховища Intlayer (кукі або користувацькі заголовки). * Якщо локаль не знайдено, відбувається відкат до переговору браузера через заголовок `Accept-Language`. * * @param event - подія запиту від SvelteKit * @returns локаль користувача */export const getLocale = (event: RequestEvent): Locale => {  const defaultLocale = configuration?.internationalization?.defaultLocale;  // Спроба отримати локаль зі сховища Intlayer (кукі або заголовки)  const storedLocale = getLocaleFromStorage({    // Доступ до cookie SvelteKit    getCookie: (name: string) => event.cookies.get(name) ?? null,    // Доступ до заголовків SvelteKit    getHeader: (name: string) => event.request.headers.get(name) ?? null,  });  if (storedLocale) {    return storedLocale;  }  // Відкат до погодження браузера по заголовку "Accept-Language"  const negotiatorHeaders: Record<string, string> = {};  // Перетворити об'єкт Headers SvelteKit у простий Record<string, string>  event.request.headers.forEach((value, key) => {    negotiatorHeaders[key] = value;  });  // Перевірити локаль із заголовка `Accept-Language`  const userFallbackLocale = localeDetector(negotiatorHeaders);  if (userFallbackLocale) {    return userFallbackLocale;  }  // Повернути локаль за замовчуванням, якщо відповідність не знайдено  return defaultLocale;};
      getLocaleFromStorage перевірятиме локаль у заголовку або cookie залежно від вашої конфігурації. Див. розділ Configuration для детальнішої інформації.
      Функція localeDetector обробляє заголовок Accept-Language і повертає найкраще співпадіння.

      Якщо локаль не налаштована, ми хочемо повернути помилку 404. Щоб спростити це, ми можемо створити функцію match, яка перевіряє, чи є локаль валідною:

      /src/params/locale.ts
      export const match = (param: Locale = defaultLocale): boolean =>  locales.includes(param);

      Примітка: Переконайтеся, що у вашому src/app.d.ts міститься визначення локалі:

      typescript
      declare global {  namespace App {    interface Locals {      locale: import("intlayer").Locale;    }  }}

      Для файлу +layout.svelte ми можемо видалити все, залишивши лише статичний вміст, не пов'язаний із i18n:

      src/+layout.svelte
      <script lang="ts">     import './layout.css';    let { children } = $props();</script><div class="app">    {@render children()}</div><style>    .app {    /*  */    }</style>

      Потім створіть нову сторінку та layout у групі [[locale=locale]]:

      src/routes/[[locale=locale]]/+layout.ts
      import type { Load } from "@sveltejs/kit";import { defaultLocale, type Locale } from "intlayer";export const prerender = true;// Використовуйте загальний тип Loadexport const load: Load = ({ params }) => {  const locale: Locale = (params.locale as Locale) ?? defaultLocale;  return {    locale,  };};
      src/routes/[[locale=locale]]/+layout.svelte
      <script lang="ts">    import type { Snippet } from 'svelte';    import { useIntlayer, setupIntlayer } from "svelte-intlayer";    import Header from './Header.svelte';    import type { LayoutData } from './$types';    let { children, data }: { children: Snippet, data: LayoutData } = $props();    // Ініціалізує Intlayer з локаллю з маршруту  $effect(() => {      setupIntlayer(data.locale);  });    // Використовує словник вмісту layout    const layoutContent = useIntlayer('layout');</script><Header /><main>    {@render children()}</main><footer>    <p>        {$layoutContent.footer.prefix.value}{' '}        <a href="https://svelte.dev/docs/kit">{$layoutContent.footer.linkLabel.value}</a>{' '}        {$layoutContent.footer.suffix.value}    </p></footer><style>  /*  */</style>
      src/routes/[[locale=locale]]/+page.ts
      export const prerender = true;
      src/routes/[[locale=locale]]/+page.svelte
      <script lang="ts">    import { useIntlayer } from "svelte-intlayer";    // Використовувати словник контенту для home    const homeContent = useIntlayer('home');</script><svelte:head>    <title>{$homeContent.title.value}</title></svelte:head><section>    <h1>        {$homeContent.title}    </h1></section><style>  /*  */</style>

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

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

      Для SEO рекомендується додавати префікс локалі до маршрутів (наприклад, /en/about, /fr/about). Цей компонент автоматично додає префікс поточної локалі до будь-якого посилання.

      src/lib/components/LocalizedLink.svelte
      <script lang="ts">  import { getLocalizedUrl } from "intlayer";  import { useLocale } from "svelte-intlayer";  let { href = "" } = $props();  const { locale } = useLocale();  // Допоміжна функція для додавання префікса локалі до URL  $: localizedHref = getLocalizedUrl(href, $locale);</script><a href={localizedHref}>  <slot /></a>

      Якщо ви використовуєте goto з SvelteKit, ви можете застосувати ту саму логіку з getLocalizedUrl, щоб перейти на локалізований URL:

      typescript
      import { goto } from "$app/navigation";import { getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";const { locale } = useLocale();const localizedPath = getLocalizedUrl("/about", $locale);goto(localizedPath); // Переходить на /en/about або /fr/about залежно від локалі

    9. Перемикач мови

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

      Щоб дозволити користувачам переключати мову, оновіть URL.

      src/lib/components/LanguageSwitcher.svelte
      <script lang="ts">  import { getLocalizedUrl, getLocaleName } from 'intlayer';  import { useLocale } from "svelte-intlayer";  import { page } from '$app/stores';  import { goto } from '$app/navigation';  const { locale, setLocale, availableLocales } = useLocale({    onLocaleChange: (newLocale) => {      const localizedPath = getLocalizedUrl($page.url.pathname, newLocale);      goto(localizedPath);    },  });</script><ul class="locale-list">  {#each availableLocales as localeEl}    <li>      <a        href={getLocalizedUrl($page.url.pathname, localeEl)}        onclick={(e) => {          e.preventDefault();          setLocale(localeEl); // Встановить локаль у store та викличе onLocaleChange        }}        class:active={$locale === localeEl}      >        {getLocaleName(localeEl)}      </a>    </li>  {/each}</ul><style>  /* */</style>

    10. Додати backend proxy

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

      Щоб додати backend proxy до вашого застосунку SvelteKit, ви можете використати функцію intlayerProxy, що надається плагіном vite-intlayer. Цей плагін автоматично визначатиме найкращу локаль для користувача на основі URL, cookies та мовних налаштувань браузера.

      vite.config.ts
      import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";import { sveltekit } from "@sveltejs/kit/vite";// https://vitejs.dev/config/export default defineConfig({  plugins: [    intlayerProxy(), // should be placed first    intlayer(),    sveltekit(),  ],],});

    11. Налаштування редактора intlayer / CMS

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

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

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

      Щоб мати змогу візуалізувати селектор редактора intlayer, потрібно використовувати синтаксис компонента у вашому контенті intlayer.

      Component.svelte
      <script lang="ts">  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("component");</script><div>  <!-- Відобразити вміст як простий контент -->  <h1>{$content.title}</h1>  <!-- Відобразити вміст як компонент (вимагається редактором) -->  {@const Component = $content.component}<Component /></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

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

    Рекомендується ігнорувати файли, згенеровані Intlayer.

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

    Далі

    • Visual Editor: Інтегруйте Intlayer Visual Editor, щоб редагувати переклади безпосередньо з UI.
    • CMS: Виносьте керування вмістом назовні, використовуючи Intlayer CMS.
    Vite та Svelte
    Vite та Preact