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

Содержание

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

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

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

Для начала создайте новый проект SvelteKit. Вот итоговая структура, которую мы создадим:

.├── 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. 1

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

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

   bash

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

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

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

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

   • intlayer: Основной пакет для i18n.
   • svelte-intlayer: Предоставляет провайдеры контекста и сторы для Svelte/SvelteKit.
   • vite-intlayer: Плагин Vite для интеграции деклараций контента в процесс сборки.
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;

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

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

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

5. 5

   Используйте Intlayer в ваших компонентах

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

   Примечание: useIntlayer возвращает Svelte store, поэтому для доступа к его реактивному значению нужно использовать префикс `--- createdAt: 2025-11-20 updatedAt: 2026-05-31 title: Как перевести ваше приложение SvelteKit – руководство по i18n 2026 description: Узнайте, как сделать ваш сайт на SvelteKit многоязычным. Следуйте документации по интернационализации (i18n) и переводу с использованием серверного рендеринга (SSR). keywords:

   • Интернационализация
   • Документация
   • Intlayer
   • SvelteKit
   • JavaScript
   • SSR slugs:
   • doc
   • environment
   • sveltekit applicationTemplate: https://github.com/aymericzip/intlayer-sveltekit-template history:
   • version: 7.1.10 date: 2025-11-20 changes: Инициализация истории

   ---

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

Содержание

Что такое Intlayer?

Intlayer, это инновационная, с открытым исходным кодом библиотека интернационализации (i18n), разработанная для упрощения поддержки многоязычности в современных веб-приложениях. Она отлично интегрируется с возможностями серверного рендеринга (SSR) в SvelteKit.

С помощью Intlayer вы можете:

• Легко управлять переводами с использованием декларативных словарей на уровне компонентов.
• Динамически локализовать метаданные, маршруты и контент.
• Обеспечить поддержку TypeScript с помощью автогенерируемых типов.
• Использовать SSR SvelteKit для SEO-оптимизированной интернационализации.

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

Для начала создайте новый проект SvelteKit. Вот итоговая структура, которую мы создадим:

.├── 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. 1

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

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

   bash

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

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

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

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

   • intlayer: Основной пакет для i18n.
   • svelte-intlayer: Предоставляет провайдеры контекста и сторы для Svelte/SvelteKit.
   • vite-intlayer: Плагин Vite для интеграции деклараций контента в процесс сборки.
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;

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

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

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

5. 5

   Используйте Intlayer в ваших компонентах

   (например, $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. 6

   Настройка маршрутизации

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

   Следующие шаги показывают, как настроить маршрутизацию на основе локали в SvelteKit. Это позволяет вашим URL включать префикс локали (например, /en/about, /fr/about) для улучшения SEO и удобства пользователей.

   bash

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

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

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

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

7. 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 (cookies или пользовательские заголовки). * Если локаль не найдена, используется fallback на браузерное определение через "Accept-Language". * * @param event - Событие запроса из SvelteKit * @returns Локаль пользователя */export const getLocale = (event: RequestEvent): Locale => {  const defaultLocale = configuration?.internationalization?.defaultLocale;  // Попытка получить локаль из хранилища Intlayer (Cookies или заголовки)  const storedLocale = getLocaleFromStorage({    // Доступ к cookies в 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";    // Использование словаря контента для домашней страницы    const homeContent = useIntlayer('home');</script><svelte:head>    <title>{$homeContent.title.value}</title></svelte:head><section>    <h1>        {$homeContent.title}    </h1></section><style>  /*  */</style>

8. 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. 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); // Установит локаль в хранилище и вызовет onLocaleChange        }}        class:active={$locale === localeEl}      >        {getLocaleName(localeEl)}      </a>    </li>  {/each}</ul><style>  /* */</style>

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

    Настройка редактора / CMS intlayer

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

    Для настройки редактора 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. 1

    Извлечение содержимого ваших компонентов

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

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

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

    Команда извлеченияКомпилятор Babel

    Запустите экстрактор для преобразования компонентов и извлечения содержимого

    bash

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

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

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

    npx intlayer extract

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

    vite.config.ts

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

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

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

    import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Добавляет плагин компилятора ],});

    bash

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

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

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

    npm run build # Или npm run dev

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

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

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

Дальнейшие шаги

• Визуальный редактор: Интегрируйте Визуальный редактор Intlayer, чтобы редактировать переводы напрямую из пользовательского интерфейса.
• CMS: Вынесите управление контентом с помощью CMS Intlayer.