Установка

Каждый шаг ниже обязателен для конфигурации, на которой работает этот сайт: локаль в URL, запоминается в cookie между визитами. Пройдите их по порядку — последний выводит на страницу переведённую строку.

Настройка через Svelte CLI #

В готовом проекте на SvelteKit 3 шаги 1–5 ниже выполняет одна команда:

npx sv add svelte-dialect   # or: bunx sv add svelte-dialect / pnpm dlx sv add svelte-dialect

Она спрашивает локали (первая становится локалью по умолчанию) и нужна ли локаль в URL, а затем:

добавляет svelte-dialect в dependencies;
создаёт src/lib/i18n.ts с createDialect;
создаёт src/lib/messages/<locale>/common.json для каждой локали с одним приветствием, которое нужно перевести;
экспортирует handle из src/hooks.server.ts (уже существующий handle оборачивается в sequence()), а если локаль в URL, то и reroute из src/hooks.ts;
добавляет плейсхолдеры lang и dir в тег <html> в src/app.html.

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

npx sv add svelte-dialect=locales:en,de+routing:yes

Останется вывести сообщение, как в шаге 6. Разделы ниже — та же настройка вручную.

Установка #

npm install svelte-dialect   # or: bun add svelte-dialect / pnpm add svelte-dialect

Требуются Svelte 5 и, для этой настройки, SvelteKit 3. Без SvelteKit импортируйте createDialect из svelte-dialect и пропустите хуки: сообщения, t() и ленивые неймспейсы работают так же, а роутинг в URL и определение локали на сервере требуют Kit.

1. Напишите сообщение #

Один JSON-файл на локаль и пространство имён: src/lib/messages/<локаль>/<пространство>.json. Значение — MessageFormat 2; для второго языка добавьте ru/common.json с тем же ключом.

src/lib/messages/en/common.json

{ "greeting": "Hello, {$name}!" }

2. Создайте диалект #

Один раз, в src/lib/i18n.ts. routing кладёт локаль в URL; без него все экспорты ниже всё равно работают, просто на конфигурации только с cookie, без префикса.

src/lib/i18n.ts

import { createDialect } from 'svelte-dialect/kit';

export const { t, handle, reroute, localizeHref, locales } = createDialect({
	messages: import.meta.glob('./messages/**/*.json', { eager: true }),
	defaultLocale: 'en',
	routing: true
});

3. Хук handle #

SvelteKit вызывает его на каждый запрос. Он определяет локаль — сначала префикс URL, потом cookie, потом Accept-Language — и записывает её в ответ по мере рендера страницы.

src/hooks.server.ts

import type { Handle } from '@sveltejs/kit/hooks';
import { handle as dialect } from '#lib/i18n.js';

export const handle: Handle = dialect;

4. Хук reroute #

Кладётся в src/hooks.ts — универсальный, не hooks.server.ts. Срезает префикс до того, как SvelteKit подбирает маршрут, так что /ru/about рендерит src/routes/about без каталога [locale].

src/hooks.ts — universal, not hooks.server.ts

import type { Reroute } from '@sveltejs/kit/hooks';
import { reroute as dialect } from '#lib/i18n.js';

export const reroute: Reroute = dialect;

5. Документ #

handle заполняет эти два плейсхолдера по мере рендера страницы.

src/app.html

<html lang="ru" dir="ltr">

6. Используйте #

Импортируйте t где угодно. Запустите dev-сервер: на странице будет «Hello, world!», а на /ru — русская строка, как только появится ru/common.json.

src/routes/+page.svelte

<script lang="ts">
	import { t } from '#lib/i18n.js';
</script>

<p>{t('common:greeting', { name: 'world' })}</p>

Дальше #

С этим на месте: напишите остальные файлы сообщений, затем прочитайте, как префикс URL и cookie решают, какую локаль увидит посетитель.