Как выбрать подходящую библиотеку i18n для Svelte

В Svelte нет встроенных инструментов для i18n: ни $t, ни примитива локали, ни формата сообщений. Любой вариант это стороннее решение. При этом экосистема Svelte продвинулась в compile-time i18n дальше остальных, поэтому кандидаты различаются между собой сильнее, чем в React или Vue.

В этом руководстве собраны вопросы, на которые нужно ответить в первую очередь, а затем ответы сопоставляются с svelte-i18n, Paraglide, typesafe-i18n, wuchale и Intlayer, как для связки Vite + Svelte, так и для SvelteKit.

Table of Contents

Шесть вопросов перед сравнением библиотек

1. Vite SPA или SvelteKit? В SPA модуль-уровневый store работает корректно: одна вкладка, один пользователь, одна локаль. В SvelteKit тот же синглтон разделяется между параллельными запросами на сервере, из-за чего запрос B может отрендериться на языке запроса A. Библиотека либо предоставляет решение per-request (context, locals), либо оставляет эту задачу вам.
2. Кто пишет переводы? Разработчики, TMS, агентство с ICU-строками или AI-pipeline. svelte-i18n работает с ICU. Paraglide и typesafe-i18n используют собственный синтаксис. Выбирайте под формат поставщика.
3. Сколько локалей и страниц? Две локали и пять страниц позволяют загружать все сразу. Десять локалей и сорок маршрутов уже нет, и разница между runtime-каталогами и скомпилированными сообщениями становится ключевым фактором накладных расходов.
4. Нужна ли типизация ключей? $_("cart.totl") в svelte-i18n приведет к ошибке во время выполнения. Compile-time библиотеки делают такую опечатку ошибкой типов на этапе компиляции.
5. Svelte 4 stores или Svelte 5 runes? Runes меняют синтаксис состояния локали, но не проблему совместного использования данных. Однако $state в файле .ts компилируется в обычную переменную, поэтому runtime библиотеки должен поддерживать runes, если вы используете Svelte 5.
6. Готовы ли вы хранить сгенерированные файлы в репозитории? Paraglide и typesafe-i18n генерируют файлы JavaScript или TypeScript прямо в исходный код. Для одних команд это приемлемо, у других вызывает merge conflicts в каждой параллельной ветке.

Запишите ответы. Все последующие разделы опираются на них.

Общая картина

i18n в Svelte появился позже, чем в React или Vue, и сразу перешел к волне решений времени компиляции.

В статье об истории i18n в JavaScript подробно рассматривается каждая волна.

Главное решение: где хранится контент и когда он загружается

Два архитектурных выбора объясняют большую часть разницы в размере bundle между решениями:

• Централизованный или изолированный контент. Один файл locales/en.json на все приложение или отдельные объявления для каждого компонента.
• Статический или динамический импорт. Загрузка всего сразу при старте или получение активной локали (и в идеале активного маршрута) по требованию.

На графике показана расчетная нагрузка для приложения от 1 до 10 страниц с переводом на 1–10 локалей при объеме текста около 30 КБ на страницу.

svelte-i18n по умолчанию находится в верхнем левом углу: вызов register("fr", () => import("./fr.json")) обеспечивает динамическую загрузку для каждой локали, но каталог локали представляет собой единый объект, поэтому при его загрузке подтягиваются тексты всех страниц. Paraglide представляет собой интересный случай: поскольку каждое сообщение является отдельным экспортом, tree-shaking автоматически разделяет страницы, и бенчмарк Svelte подтверждает эффективность на Vite + Svelte (в бенчмарках React и Next.js этого не происходило). Intlayer достигает аналогичных показателей за счет объявлений на уровне компонентов.

Если в вопросе 3 вы указали «много страниц», уделите этому разделу больше внимания, чем предпочтениям в API. В статье о колокации против централизованного i18n подробно описана сторона поддержки этого компромисса.

Кандидаты

Размеры библиотек взяты из бенчмарка Svelte: store плюс аксессор в пустом компоненте после сборки, tree-shaking и минификации в приложении на 10 страниц и 10 локалей. Объем контента измеряется отдельно.

Цифры отражают состояние на момент тестирования версий бенчмарка. Проверьте показатели на собственном приложении перед принятием решения исключительно по размеру.

Почти нулевой размер Paraglide обусловлен его архитектурой: runtime генерируется прямо в репозиторий. Для работы Intlayer требуется vite-intlayer, поэтому он не может работать без шага build.

Сопоставление требований с библиотекой

Недостатки библиотек

• svelte-i18n: самая тяжелая библиотека из представленных, нет типизации ключей, нет разделения по маршрутам, а store уровня модуля приводит к утечкам состояния между запросами на SvelteKit, если не настроить context вручную.
• typesafe-i18n: требует отдельного процесса watcher, генерирует файлы в репозитории, а разработка проекта в последнее время практически не ведется.
• Paraglide: сгенерированные файлы коммитятся в репозиторий и пересоздаются перед каждым push, что приводит к merge conflicts в параллельных ветках; локаль считывается из cookie или storage при каждом вызове сообщения, а не берется из store, создавая дополнительную нагрузку при смене языка.
• wuchale: интересная идея извлечения строк, но проект находится на ранней стадии. В бенчмарке React возникли проблемы с реактивностью, потребовавшие принудительного ререндера провайдера, а документация пока минимальна.
• Intlayer: требует обязательного плагина сборки, меньшая экосистема, частичная поддержка ICU и распределение контента по проекту, из-за чего для экспорта единого JSON переводчику нужны дополнительные инструменты.

Примеры кода

Один и тот же компонент корзины с заголовком и формой множественного числа, реализованный на каждом из кандидатов. Главные различия заключаются не в разметке, а в том, где хранится контент, как устроено состояние локали и что доступно проверке типов.

{
  "cart": {
    "title": "Your cart",
    "items": "{count, plural, one {# item} other {# items}}"
  }
}

<script lang="ts">
  import { _ } from "svelte-i18n";

  let { count }: { count: number } = $props();
</script>

<section>
  <h2>{$_("cart.title")}</h2>
  <p>{$_("cart.items", { values: { count } })}</p>
</section>

{
  "cart_title": "Your cart",
  "cart_items": "{count} items"
}

<script lang="ts">
  import { m } from "$lib/paraglide/messages.js";

  let { count }: { count: number } = $props();
</script>

<section>
  <h2>{m.cart_title()}</h2>
  <p>{m.cart_items({ count })}</p>
</section>

import type { BaseTranslation } from "../i18n-types";

const en = {
  cart: {
    title: "Your cart",
    items: "{count} item{{s}}",
  },
} satisfies BaseTranslation;

export default en;

<script lang="ts">
  import LL from "$i18n/i18n-svelte";

  let { count }: { count: number } = $props();
</script>

<section>
  <h2>{$LL.cart.title()}</h2>
  <p>{$LL.cart.items({ count })}</p>
</section>

import { plural, t, type Dictionary } from "intlayer";

const cartSummaryContent = {
  key: "cart-summary",
  content: {
    title: t({
      ru: "Ваша корзина",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      ru: plural({
        one: "{{count}} товар",
        few: "{{count}} товара",
        many: "{{count}} товаров",
        other: "{{count}} товаров",
      }),
      en: plural({ one: "{{count}} item", other: "{{count}} items" }),
      fr: plural({ one: "{{count}} article", other: "{{count}} articles" }),
      es: plural({ one: "{{count}} artículo", other: "{{count}} artículos" }),
    }),
  },
} satisfies Dictionary;

export default cartSummaryContent;

<script lang="ts">
  import { useIntlayer } from "svelte-intlayer";

  let { count }: { count: number } = $props();
  const content = useIntlayer("cart-summary");
</script>

<section>
  <h2>{$content.title}</h2>
  <p>{$content.items(count)}</p>
</section>

Уже используете svelte-i18n? Адаптер совместимости @intlayer/svelte-i18n создает алиас пакета на уровне bundler, сохраняя работоспособность $_, $date, $number и плоских ключей, пока Intlayer управляет контентом.

Перед принятием окончательного решения

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

Проверьте активность репозитория.

Обратите внимание на коммиты, скорость ответов в issues и дату последнего минорного релиза. Качественная архитектура без активного мейнтейнера со временем неизбежно потребует миграции.

Не выбирайте исключительно по числу загрузок в npm.

Самая скачиваемая библиотека это та, которая появилась первой, а не та, которая лучше всего подходит для Svelte в 2026 году. Количество загрузок отражает историю, а не актуальность.

Узнайте, кто финансирует поддержку и какую бизнес-модель использует.

Разработку svelte-i18n поддерживает Crowdin, как и next-intl с vue-i18n. За i18next стоит Locize. Tolgee, Paraglide (inlang) и Intlayer развивают собственные платформы. Поставщик, чей доход зависит от платного хостинга переводов, мало заинтересован в развитии бесплатных инструментов внутри вашего toolchain. Intlayer является единственным решением из списка, предлагающим AI-перевод через CLI с вашим собственным API-ключом и self-hosted CMS.

Готовность к работе с AI-агентами.

Агенты все еще допускают ошибки в i18n: забывают локали, придумывают несуществующие ключи и путают синтаксис сообщений. Предлагает ли библиотека Agent Skills или MCP-сервер, чтобы агент мог просматривать, заполнять и тестировать контент? Оптимизирована ли загрузка контента по умолчанию, или команде придется регулярно пересматривать namespaces и динамические импорты?

Типизация из коробки.

Речь идет не о «возможности настроить типы вручную», а о ситуации, когда неверный ключ приводит к ошибке tsc сразу после установки. Проверьте, как библиотека реагирует на несуществующий ключ и на локаль с отсутствующим переводом.

Обнаружение неиспользуемого контента.

Каталоги со временем только увеличиваются. Сборка Intlayer удаляет неиспользуемые поля и логирует их (build.purge). Paraglide решает эту задачу на уровне архитектуры: невызываемая функция сообщения удаляется при tree-shaking. Остальные инструменты оставляют очистку на усмотрение разработчика.

Удобство для разработчиков (DX).

Время от начала настройки до первой переведенной строки, наличие LSP или расширения VS Code с подсказками при наведении и переходом к объявлению, CLI для генерации, тестирования и отправки переводов, а также возможность редактирования контента специалистами без участия разработчиков (визуальный редактор или CMS) без создания pull request.

Часто задаваемые вопросы

Полезные материалы

• Бенчмарк i18n для Svelte: размер bundle, утечки контента и скорость переключения локалей
• i18n в Svelte: stores, runes и ловушка синглтонов уровня модуля и i18n в SvelteKit: роутинг, SSR и разделяемое состояние
• Адаптер совместимости с svelte-i18n
• История i18n в JavaScript
• Компиляторы против декларативного i18n
• Колокация контента против централизованного i18n
• Как работает оптимизация bundle на этапе сборки
• Настройка i18n в приложении Vite + Svelte и в SvelteKit
• Аналогичные руководства для React, Vue и Solid