Skip to main content

SvelteKit i18n: configuratiehandleiding voor internationalisatie

Van nul naar meertalig: configureer svelte-i18n in je SvelteKit-app met de ICU-berichtindeling, taalgebaseerde routering en slimme terugvalketens.

1

svelte-i18n installeren

svelte-i18n is de standaardbibliotheek voor internationalisatie in Svelte en SvelteKit. De bibliotheek biedt standaard reactieve stores, ondersteuning voor ICU MessageFormat en uitgesteld laden van talen.

svelte-i18n gebruikt ICU MessageFormat voor meervoudsvormen en variabelen — dezelfde standaard als FormatJS/react-intl. Als je uit de React-wereld komt, zal de berichtsyntaxis je bekend voorkomen.
Terminal
npm install svelte-i18n
2

svelte-i18n configureren

Maak een i18n-configuratiebestand dat je talen registreert met uitgesteld geladen importfuncties. svelte-i18n haalt de berichten van een taal pas op wanneer die taal wordt geactiveerd.

src/lib/i18n.ts
// src/lib/i18n.ts
import { register, init, getLocaleFromNavigator } from 'svelte-i18n';

// Register locale loaders (lazy-loaded)
register('en', () => import('../locales/en.json'));
register('de', () => import('../locales/de.json'));
register('ja', () => import('../locales/ja.json'));
register('es', () => import('../locales/es.json'));

init({
  fallbackLocale: 'en',
  initialLocale: getLocaleFromNavigator(),  // Auto-detect browser language
});
Je moet je i18n-configuratiebestand in +layout.svelte importeren voordat een component wordt weergegeven. Als vertalingen onbewerkte sleutels zoals 'nav.home' tonen, is de configuratie niet vroeg genoeg geïmporteerd.

Integratie met de SvelteKit-lay-out

Importeer je i18n-configuratie in de hoofdlayout en scherm de weergave af met de store $isLoading. Zo voorkom je dat onvertaalde sleutels kort in beeld komen terwijl taalgegevens asynchroon worden geladen.

src/routes/+layout.svelte
<!-- src/routes/+layout.svelte -->
<script>
  // Import i18n config — must run before any component renders
  import '../lib/i18n';
  import { isLoading } from 'svelte-i18n';
</script>

{#if $isLoading}
  <p>Loading translations...</p>
{:else}
  <slot />
{/if}

Taalgebaseerde routering in SvelteKit

Gebruik voor SEO-vriendelijke URL's zoals /en/about en /de/about een routeparameter [lang]. Stel de taal van svelte-i18n in de load-functie van de lay-out in op basis van de URL-parameter.

SvelteKit locale routing
// src/routes/[lang]/+layout.ts
import { locale } from 'svelte-i18n';

export function load({ params }) {
  // Set the active locale from the URL parameter
  locale.set(params.lang);
  return {};
}

// src/routes/[lang]/+layout.svelte
<script>
  import '../../lib/i18n';
  import { isLoading } from 'svelte-i18n';
</script>

{#if $isLoading}
  <p>Loading...</p>
{:else}
  <slot />
{/if}

Indeling van vertaalbestanden

Maak voor elke taal één JSON-bestand. svelte-i18n ondersteunt geneste sleutels en ICU MessageFormat-syntaxis voor meervoudsvormen, variabelen en select-expressies.

Translation files
// src/locales/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {name}!",
  "cart": {
    "itemCount": "{count, plural, one {# item} other {# items}}"
  }
}

// src/locales/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Uber uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {name}!",
  "cart": {
    "itemCount": "{count, plural, one {# Artikel} other {# Artikel}}"
  }
}
Geef sleutels een naam op basis van wat ze beschrijven, niet waar ze staan: 'cart.itemCount' is beter dan 'homepageCartLabel'. Sleutels moeten herontwerpen van de interface overleven.
3

Vertalingen in componenten gebruiken

Importeer de store $_ (of $format) uit svelte-i18n en gebruik deze in je Svelte-sjablonen. De store is reactief: wanneer de taal verandert, worden alle vertaalde tekenreeksen automatisch bijgewerkt.

Component.svelte
<script>
  import { _ } from 'svelte-i18n';
</script>

<h1>{$_('greeting', { values: { name: 'World' } })}</h1>

<nav>
  <a href="/">{$_('nav.home')}</a>
  <a href="/about">{$_('nav.about')}</a>
</nav>
Formatting helpers
<script>
  import { _, date, number, time } from 'svelte-i18n';
</script>

<!-- Simple string -->
<p>{$_('greeting', { values: { name: userName } })}</p>

<!-- ICU plurals — handled automatically -->
<p>{$_('cart.itemCount', { values: { count: 3 } })}</p>

<!-- Date formatting -->
<p>{$date(new Date(), { format: 'long' })}</p>

<!-- Number formatting -->
<p>{$number(1999.99, { style: 'currency', currency: 'USD' })}</p>
$_ is een Svelte-store — in sjablonen moet je het voorvoegsel $ gebruiken. Als je _('key') zonder dollarteken schrijft, krijg je het storeobject terug en niet de vertaalde tekenreeks.

Van taal wisselen

Bouw een taalselector die aan de store $locale is gekoppeld. Wanneer de waarde verandert, laadt svelte-i18n de berichten van de nieuwe taal en werkt de bibliotheek alle vertaalde tekenreeksen reactief bij.

LanguageSwitcher.svelte
<script>
  import { locale, locales } from 'svelte-i18n';

  const LANGUAGE_NAMES = {
    en: 'English',
    de: 'Deutsch',
    ja: '日本語',
    es: 'Espanol',
  };
</script>

<select bind:value={$locale}>
  {#each $locales as loc}
    <option value={loc}>{LANGUAGE_NAMES[loc] ?? loc}</option>
  {/each}
</select>
4

Meervoudsvormen verwerken met ICU MessageFormat

svelte-i18n gebruikt ICU MessageFormat voor meervoudsvormen, de internationale standaard die alle CLDR-meervoudscategorieën verwerkt. Arabisch heeft 6 vormen, Russisch 4 en Japans 1. Definieer de vormen die je doeltalen nodig hebben, waarna svelte-i18n automatisch de juiste selecteert.

ICU plural forms by language
// svelte-i18n uses ICU MessageFormat for plurals
// English:
{
  "items": "{count, plural, one {# item} other {# items}}"
}

// Arabic (6 forms):
{
  "items": "{count, plural, zero {no items} one {item} two {two items} few {# items} many {# items} other {# items}}"
}

// Japanese (1 form):
{
  "items": "{count, plural, other {#個のアイテム}}"
}
Codeer logica voor enkelvoud en meervoud nooit hard in je componenten. Talen zoals het Frans behandelen 0 als enkelvoud. Het Arabisch, Russisch en Pools hebben meervoudsvormen die het Engels niet kent. Laat de ICU-meervoudssyntaxis dit verwerken.

Slimme terugvaltalen met svelte-i18n-locale-chain

svelte-i18n valt bij een ontbrekende sleutel direct terug op fallbackLocale — er is geen tussenliggende terugval. Een gebruiker met pt-BR ziet Engels in plaats van prima pt-PT-vertalingen. svelte-i18n-locale-chain lost dit op met slimme terugvalketens die berichten uit regionale varianten diep samenvoegen.

Terminal
npm install svelte-i18n-locale-chain svelte-i18n
src/lib/i18n.ts
// src/lib/i18n.ts
import { initLocaleChain, setLocale } from 'svelte-i18n-locale-chain';

// Replace svelte-i18n's init + register with initLocaleChain
await initLocaleChain({
  loadMessages: (locale) =>
    import(`../locales/${locale}.json`).then(m => m.default),
  defaultLocale: 'en',
  initialLocale: 'pt-BR',
});

// Later, to change locale:
await setLocale('fr-CA');
// fr-CA user sees: fr-CA messages -> fr messages -> en messages
// No missing keys — deep-merged automatically
svelte-i18n-locale-chain beheert intern het laden van alle berichten. Gebruik daarnaast niet de functie register() van svelte-i18n — initLocaleChain verzorgt de registratie, het laden en het diep samenvoegen.

Vertalingen automatiseren

Nu i18n is geconfigureerd, kun je je taalbestanden met AI vertalen. Vraag je AI-assistent in je IDE om je bronbestand te vertalen of gebruik de CLI van i18n Agent in je CI/CD-pipeline.

Terminal
# In your IDE, ask your AI assistant:
> Translate src/locales/en.json to German, Japanese, and Spanish

✓ de.json created (1.2s)
✓ ja.json created (1.5s)
✓ es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate src/locales/en.json --lang de,ja,es
Vertaal stapsgewijs: vertaal alleen de wijzigingen wanneer je nieuwe sleutels aan het bronbestand toevoegt, in plaats van alle bestanden opnieuw te genereren. Zo blijven door mensen beoordeelde vertalingen behouden.

Kwaliteitscontrole van vertalingen automatiseren

Vind ontbrekende sleutels en kapotte plaatsaanduidingen vóór de release met i18n-validate. Test je gebruikersinterface met pseudovertalingen uit i18n-pseudo voordat de echte vertalingen klaar zijn.

Veelvoorkomende valkuilen

Taal lekt tussen SSR-verzoeken in SvelteKit

svelte-i18n-stores zijn singletons. Bij SSR in SvelteKit delen gelijktijdige verzoeken dezelfde store, waardoor de taal van de ene gebruiker in het antwoord van een andere kan belanden. Oplossing: roep locale.set() aan in de handle-hook of load-functie van de lay-out, zodat elk verzoek de juiste taalcontext krijgt.

register() gebruiken met svelte-i18n-locale-chain

Gebruik de functie register() van svelte-i18n niet als je svelte-i18n-locale-chain gebruikt. initLocaleChain verzorgt intern het laden van alle berichten. Als je beide combineert, worden berichten dubbel of tegenstrijdig geladen.

ICU-syntaxisfouten mislukken zonder melding

Een niet-overeenkomend haakje of ontbrekende meervoudscategorie in ICU MessageFormat-tekenreeksen veroorzaakt een stille fout: de onbewerkte berichttekenreeks verschijnt in plaats van de opgemaakte uitvoer. Valideer ICU-syntaxis in je CI-pipeline.

Onvertaalde inhoud komt kort in beeld

Als je componenten weergeeft voordat de vertalingen zijn geladen, zien gebruikers onbewerkte sleutels. Scherm je lay-out af met {#if $isLoading}...{:else}...{/if} om een laadstatus te tonen totdat de berichten klaar zijn.

Aanbevolen bestandsstructuur

Project Structure
my-sveltekit-app/
├── src/
│   ├── lib/
│   │   └── i18n.ts              # i18n configuration
│   ├── locales/
│   │   ├── en.json              # Source language
│   │   ├── de.json              # German
│   │   ├── ja.json              # Japanese
│   │   └── es.json              # Spanish
│   └── routes/
│       ├── +layout.svelte       # Import i18n, guard isLoading
│       ├── +page.svelte
│       └── [lang]/              # Optional: locale-based routing
│           ├── +layout.ts       # Set locale from URL param
│           ├── +layout.svelte
│           └── +page.svelte
├── svelte.config.js
└── package.json

Probeer i18n Agent nu

Zet je vertaalbestand hier neer

JSON, YAML, PO, XML, CSV, Markdown, Properties

of klik om een bestand te selecteren

Doeltalen

Geen registratie nodigDirecte prijsindicatie

Terugvaltalen met svelte-i18n-locale-chain

Als een vertaalsleutel ontbreekt in een regionale taal zoals pt-BR, schakelt svelte-i18n direct over naar de standaardtaal in plaats van eerst de bovenliggende taal pt te controleren.

Terminal
npm install svelte-i18n-locale-chain
Configuration
import { initLocaleChain } from 'svelte-i18n-locale-chain';

initLocaleChain({
  fallbacks: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
  },
  defaultLocale: 'en',
});

Bekijk onze handleiding voor terugvaltalen voor de volledige lijst met ondersteunde frameworks en 75 ingebouwde ketens. Learn more →

Veelgestelde vragen