Jak wybrać odpowiednią bibliotekę i18n dla Svelte

Svelte nie dostarcza żadnych wbudowanych narzędzi do i18n. Brak $t, brak prymitywu locale, brak formatu wiadomości. Każda opcja to rozwiązanie zewnętrzne, a ekosystem Svelte to miejsce, w którym i18n w czasie kompilacji poszło najdalej, dlatego poszczególni kandydaci różnią się od siebie bardziej niż w przypadku React czy Vue.

Ten przewodnik wymienia pytania, na które warto odpowiedzieć w pierwszej kolejności, a następnie przypisuje odpowiedzi do svelte-i18n, Paraglide, typesafe-i18n, wuchale i Intlayer, zarówno dla Vite + Svelte, jak i dla SvelteKit.

Spis treści

Sześć pytań, na które należy odpowiedzieć przed porównaniem bibliotek

1. Vite SPA czy SvelteKit? W SPA store na poziomie modułu jest poprawny: jedna karta, jeden użytkownik, jedno locale. W SvelteKit ten sam singleton jest współdzielony między równoległymi żądaniami na serwerze, przez co żądanie B może wyrenderować się w języku żądania A. Biblioteka albo zapewnia strukturę dla każdego żądania (context, locals), albo pozostawia jej implementację Tobie.
2. Kto pisze tłumaczenia? Programiści, TMS, agencja dostarczająca ciągi ICU, czy pipeline AI. svelte-i18n obsługuje ICU. Paraglide i typesafe-i18n używają własnej składni. Dopasuj rozwiązanie do dostawcy treści.
3. Ile masz wersji językowych (locales) i podstron? Dwa języki i pięć podstron mogą wysłać wszystko do klienta. Dziesięć języków i czterdzieści tras już nie, a różnica między katalogami runtime a skompilowanymi wiadomościami staje się głównym kosztem.
4. Czy potrzebujesz typowania kluczy? $_("cart.totl") to błąd w runtime w svelte-i18n. Biblioteki czasu kompilacji czynią z tego błąd typowania już na etapie kompilacji.
5. Store'y ze Svelte 4 czy runes ze Svelte 5? Runes zmieniają składnię stanu locale, a nie problem współdzielenia stanu. Jednak $state w pliku .ts kompiluje się do zwykłej zmiennej, więc runtime biblioteki musi obsługiwać runes, jeśli korzystasz ze Svelte 5.
6. Czy akceptujesz wygenerowane pliki w repozytorium? Zarówno Paraglide, jak i typesafe-i18n generują kod JavaScript lub TypeScript bezpośrednio w Twoim drzewie źródłowym. Dla niektórych zespołów to żaden problem, inni mierzą się z konfliktami scalania (merge conflicts) na każdej równoległej gałęzi.

Zapisz swoje odpowiedzi. Wszystkie poniższe sekcje będą się do nich odnosić.

Krajobraz w jednym ujęciu

i18n w Svelte pojawiło się później niż w React czy Vue i od razu przeszło do fal opartych na kompilacji.

Artykuł historia JavaScript i18n szczegółowo opisuje każdą z tych fal.

Decyzja, która ma największe znaczenie: gdzie znajduje się treść i kiedy jest ładowana

Dwa wybory strukturalne odpowiadają za większość różnic w rozmiarze bundle między konfiguracjami:

• Treść scentralizowana lub per komponent (scoped). Jeden plik locales/en.json dla całej aplikacji lub pojedyncza deklaracja obok każdego komponentu.
• Import statyczny lub dynamiczny. Wszystko ładowane przy starcie albo aktywne locale (oraz optymalnie aktywna trasa) pobierane na żądanie.

Wykres szacuje payload dla teoretycznej aplikacji mającej od 1 do 10 podstron, przetłumaczonej na 1 do 10 języków, z około 30 KB tekstu na stronę.

svelte-i18n domyślnie znajduje się w lewym górnym rogu: register("fr", () => import("./fr.json")) zapewnia dynamiczne ładowanie dla każdego locale, ale katalog danego języka to jeden obiekt i załadowanie go powoduje wczytanie treści wszystkich podstron. Paraglide to interesujący przypadek: ponieważ każda wiadomość jest osobnym exportem, tree-shaking zapewnia podział na poziomie podstron bez dodatkowej pracy, a benchmark Svelte potwierdza, że działa to zgodnie z opisem w Vite + Svelte (w benchmarkach React i Next.js tak nie było). Intlayer osiąga ten sam rezultat dzięki deklaracjom na poziomie pojedynczych komponentów.

Jeśli Twoją odpowiedzią na pytanie 3 było "wiele podstron", potraktuj tę sekcję priorytetowo ponad preferencjami dotyczącymi API. Wpis i18n per komponent a scentralizowane omawia kwestię utrzymania tego samego kompromisu.

Kandydaci

Rozmiary bibliotek pochodzą z benchmarku Svelte: store wraz z akcesorem w pustym komponencie, po bundle, tree-shakingu i minifikacji, w aplikacji z 10 podstronami i 10 wersjami językowymi. Sama treść jest mierzona osobno.

Liczby są migawką dla wersji z benchmarku. Uruchom go na własnej aplikacji przed podjęciem decyzji opartej wyłącznie na rozmiarze.

Rozmiar biblioteki Paraglide bliski zeru wynika z jej konstrukcji: runtime jest generowany bezpośrednio do Twojego repozytorium. Intlayer wymaga wtyczki vite-intlayer, więc nie działa bez kroku budowania.

Dopasuj swoje odpowiedzi do biblioteki

Gdzie każda biblioteka ma słabe punkty

• svelte-i18n: najcięższa z zestawu, brak typów dla kluczy, brak podziału per trasa, store na poziomie modułu, który wycieka między żądaniami w SvelteKit, chyba że samodzielnie skonfigurujesz context.
• typesafe-i18n: proces obserwatora (watcher), generowane pliki w repozytorium oraz repozytorium, które nie było ostatnio aktywnie rozwijane.
• Paraglide: generowane pliki commitowane do repozytorium i regenerowane przed każdym pushem, konflikty scalania na równoległych gałęziach oraz locale odczytywane z cookie lub storage przy każdym wywołaniu wiadomości zamiast ze store'a, co generuje narzut przy zmianie języka.
• wuchale: ciekawy pomysł na ekstrakcję, ale wciąż wczesny etap. Benchmark React napotkał problemy z reaktywnością, które wymagały wymuszania ponownego renderowania providera, a dokumentacja jest skromna.
• Intlayer: wymagana wtyczka do buildera, mniejszy ekosystem, częściowe wsparcie ICU oraz treść rozproszona po całej bazie kodu z założenia, więc wyeksportowanie pojedynczego pliku JSON dla tłumacza wymaga dodatkowych narzędzi.

Jak każda opcja wygląda w kodzie

Ten sam komponent, podsumowanie koszyka z tytułem i liczbą mnogą, napisany przy użyciu każdego kandydata. Najciekawszą częścią nie jest sam markup, lecz to, gdzie znajduje się treść, jak przechowywane jest locale i co wie system typów.

{
  "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({
      pl: "Twój koszyk",
      en: "Your cart",
      fr: "Votre panier",
      es: "Tu carrito",
    }),
    items: t({
      pl: plural({
        one: "{{count}} produkt",
        few: "{{count}} produkty",
        many: "{{count}} produktów",
        other: "{{count}} produktów",
      }),
      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>

Korzystasz już z svelte-i18n? Adapter kompatybilności @intlayer/svelte-i18n tworzy alias dla pakietu na poziomie bundlera, dzięki czemu $_, $date, $number oraz Twoje płaskie klucze nadal działają, podczas gdy Intlayer dostarcza treść.

Zanim podejmiesz decyzję

Tabela funkcji mówi o tym, co biblioteka potrafi dzisiaj. Poniższe punkty pokazują, jak będzie wyglądać codzienna praca z nią.

Sprawdź aktywność repozytorium.

Commity, czas odpowiedzi na zgłoszenia (issues) oraz informacja, czy ostatnie wydanie minor miało miejsce w tym roku. Dobry projekt bez maintainera to odroczona w czasie migracja.

Nie wybieraj na podstawie liczby pobrań z npm.

Najczęściej instalowana biblioteka to ta, która powstała jako pierwsza, a nie ta, która najlepiej pasuje do bazy kodu Svelte w 2026 roku. Liczba pobrań mierzy historię, a nie dopasowanie.

Sprawdź, kto finansuje maintainera i co sprzedaje.

svelte-i18n jest wspierane przez Crowdin, podobnie jak next-intl czy vue-i18n. i18next jest wspierane przez Locize. Tolgee, Paraglide (inlang) oraz Intlayer prowadzą własne platformy. Dostawca, którego przychód zależy od hostowanych tłumaczeń, nie ma motywacji, aby tłumaczenie wewnątrz Twojego toolchaina było bezpłatne. Intlayer jako jedyny z tego zestawu dostarcza tłumaczenie AI przez CLI z Twoim własnym kluczem API oraz CMS, który możesz samodzielnie hostować.

Czy rozwiązanie jest gotowe na agentów AI?

Agenci AI wciąż miewają trudności z i18n: zapominają o wersjach językowych, wymyślają klucze i mieszają składnie wiadomości. Czy biblioteka dostarcza Agent Skills lub serwer MCP, aby agent mógł listować, uzupełniać i testować treści? Oraz czy ładowanie treści jest domyślnie zoptymalizowane, czy też ktoś musi co kwartał robić przegląd przestrzeni nazw (namespaces) i dynamicznych importów?

Bezpieczeństwo typów od pierwszego uruchomienia.

Nie "możliwe do otypowania po dodatkowej konfiguracji", ale "błędny klucz powoduje błąd tsc zaraz po instalacji". Sprawdź, co się dzieje z kluczem, który nie istnieje, oraz z językiem, w którym brakuje jednego tłumaczenia.

Wykrywanie nieużywanej treści.

Katalogi mają tendencję wyłącznie do rozrastania się. Build Intlayer usuwa nieużywane pola i raportuje je (build.purge). Paraglide osiąga to dzięki swojej architekturze, ponieważ niewywołana funkcja wiadomości jest usuwana w procesie tree-shaking. Każda inna biblioteka pozostawia to zadanie Tobie.

Doświadczenie programisty (Developer Experience).

Czas od konfiguracji do pierwszego przetłumaczonego tekstu, LSP lub rozszerzenie do VS Code, które wyświetla tłumaczenie po najechaniu kursorem i przenosi do deklaracji, CLI do uzupełniania, testowania i publikowania oraz sposób na edycję treści dla osób nietechnicznych (edytor wizualny lub CMS) bez konieczności tworzenia pull requesta.

Często zadawane pytania

Idąc dalej

• Benchmark Svelte i18n: rozmiar bundle, wycieki i czasy przełączania locale
• Svelte i18n: store'y, runes i pułapka na poziomie modułu oraz SvelteKit i18n: routing, SSR i współdzielony stan
• Gotowy adapter kompatybilności svelte-i18n
• Historia JavaScript i18n
• Kompilator a deklaratywne i18n
• i18n per komponent a scentralizowane
• Jak działa optymalizacja bundle podczas budowania
• Konfiguracja i18n w aplikacji Vite + Svelte oraz w aplikacji SvelteKit
• Ten sam przewodnik dla React, Vue oraz Solid