Skip to main content

SvelteKit i18n: internacionalizavimo sąrankos vadovas

Nuo nulio iki kelių kalbų: sukonfigūruokite svelte-i18n SvelteKit programoje su ICU pranešimų formatu, lokalėmis pagrįstais maršrutais ir išmaniomis atsarginėmis grandinėmis.

1

Įdiegti svelte-i18n

svelte-i18n yra standartinė Svelte ir SvelteKit internacionalizavimo biblioteka. Ji iškart suteikia reaktyviąsias saugyklas, ICU MessageFormat palaikymą ir tingųjį lokalių įkėlimą.

svelte-i18n daugiskaitai ir kintamiesiems naudoja ICU MessageFormat – tą patį standartą kaip FormatJS/react-intl. Jei pereinate iš React, pranešimų sintaksė bus pažįstama.
Terminal
npm install svelte-i18n
2

Sukonfigūruoti svelte-i18n

Sukurkite i18n konfigūracijos failą, kuris registruoja lokales su tingiai įkeliamomis importavimo funkcijomis. svelte-i18n gaus lokalės pranešimus tik tada, kai lokalė suaktyvinama.

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
});
i18n konfigūracijos failą turite importuoti +layout.svelte prieš atvaizduojant bet kurį komponentą. Jei vertimuose rodomi neapdoroti raktai, pavyzdžiui, „nav.home“, konfigūracija importuota per vėlai.

SvelteKit maketo integracija

Importuokite i18n konfigūraciją šakniniame makete ir apsaugokite atvaizdavimą saugykla $isLoading. Taip, kol lokalės duomenys įkeliami asinchroniškai, trumpam neparodomi neišversti raktai.

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}

Lokalėmis pagrįsti maršrutai SvelteKit

SEO tinkamiems URL, pavyzdžiui, /en/about ir /de/about, naudokite maršruto parametrą [lang]. Nustatykite svelte-i18n lokalę maketo funkcijoje load pagal URL parametrą.

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}

Vertimo failo formatas

Sukurkite po vieną JSON failą kiekvienai lokalei. svelte-i18n palaiko įdėtinius raktus ir ICU MessageFormat sintaksę daugiskaitai, kintamiesiems bei pasirinkimo išraiškoms.

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}}"
  }
}
Raktus pavadinkite pagal tai, ką jie apibūdina, o ne kur rodomi: „cart.itemCount“ geriau nei „homepageCartLabel“. Raktai turėtų išlikti pertvarkius UI.
3

Naudoti vertimus komponentuose

Importuokite saugyklą $_ (arba $format) iš svelte-i18n ir naudokite ją Svelte šablonuose. Saugykla reaktyvioji: pasikeitus lokalei visos išverstos eilutės atnaujinamos automatiškai.

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>
$_ yra Svelte saugykla, todėl šablonuose turite naudoti prefiksą $. Parašius _('key') be dolerio ženklo grąžinamas saugyklos objektas, o ne išversta eilutė.

Kalbos keitimas

Sukurkite kalbos parinkiklį, susietą su saugykla $locale. Pasikeitus reikšmei svelte-i18n įkelia naujos lokalės pranešimus ir reaktyviai atnaujina visas išverstas eilutes.

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

Apdoroti daugiskaitą ICU MessageFormat

svelte-i18n daugiskaitai naudoja ICU MessageFormat – tarptautinį standartą, apdorojantį visas CLDR daugiskaitos kategorijas. Arabų kalboje yra 6 formos, rusų – 4, japonų – 1. Apibrėžkite tikslinėms kalboms būtinas formas, o svelte-i18n automatiškai parinks tinkamą.

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 {#個のアイテム}}"
}
Niekada komponentuose tiesiogiai neįrašykite vienaskaitos ir daugiskaitos logikos. Tokiose kalbose kaip prancūzų 0 laikomas vienaskaita. Arabų, rusų ir lenkų kalbos turi anglų kalboje neegzistuojančių daugiskaitos formų. Leiskite jas apdoroti ICU daugiskaitos sintaksei.

Išmanios atsarginės lokalės su svelte-i18n-locale-chain

Kai nėra rakto, svelte-i18n iškart grįžta prie fallbackLocale – tarpinio atsarginio varianto nėra. pt-BR naudotojas vietoje puikių pt-PT vertimų mato anglų kalbą. svelte-i18n-locale-chain tai ištaiso išmaniomis atsarginėmis grandinėmis, giliai sujungiančiomis regioninių variantų pranešimus.

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 visą pranešimų įkėlimą valdo viduje. Kartu su juo nenaudokite svelte-i18n funkcijos register() – initLocaleChain tvarko registravimą, įkėlimą ir gilųjį sujungimą.

Automatizuoti vertimus

Baigę i18n sąranką išverskite lokalės failus naudodami DI. IDE paprašykite DI asistento išversti šaltinio failą arba CI/CD konvejeryje naudokite i18n Agent CLI.

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
Verskite palaipsniui – pridėję naujų raktų prie šaltinio failo išverskite tik skirtumą, o ne generuokite visus failus iš naujo. Taip išsaugosite žmonių peržiūrėtus vertimus.

Automatizuoti vertimo kokybę

Naudodami i18n-validate prieš išleidimą aptikite trūkstamus raktus ir sugadintus vietos rezervavimo ženklus. Kol dar nėra tikrų vertimų, patikrinkite UI su i18n-pseudo pseudoverstimais.

Dažnos klaidos

SSR lokalės persidengimas SvelteKit

svelte-i18n saugyklos yra vienetiniai objektai. SvelteKit SSR aplinkoje vienalaikės užklausos bendrina tą pačią saugyklą, todėl vieno naudotojo lokalė gali patekti į kito atsakymą. Sprendimas: iškvieskite locale.set() kablio handle arba maketo funkcijoje load, kad kiekviena užklausa gautų tinkamą lokalės kontekstą.

register() naudojimas su svelte-i18n-locale-chain

Jei naudojate svelte-i18n-locale-chain, nenaudokite svelte-i18n funkcijos register(). initLocaleChain visą pranešimų įkėlimą tvarko viduje. Sumaišius abi funkcijas pranešimai įkeliami dukart arba kyla konfliktų.

ICU sintaksės klaidos įvyksta tyliai

Neatitinkantis skliaustas ar trūkstama daugiskaitos kategorija ICU MessageFormat eilutėse sukelia tylią klaidą – vietoje suformatuotos išvesties rodoma neapdorota pranešimo eilutė. Tikrinkite ICU sintaksę CI konvejeryje.

Trumpam parodomas neišverstas turinys

Jei komponentus atvaizduojate dar nebaigus įkelti vertimų, naudotojai mato neapdorotus raktus. Apsaugokite maketą su {#if $isLoading}...{:else}...{/if}, kad iki pranešimų parengimo rodytumėte įkėlimo būseną.

Rekomenduojama failų struktūra

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

Išbandykite i18n Agent dabar

Nuvilkite vertimo failą čia

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

arba spustelėkite norėdami pasirinkti

Tikslinės kalbos

Registruotis nereikiaMomentinis įvertis

Atsarginė lokalė su svelte-i18n-locale-chain

Kai regioninėje lokalėje, pavyzdžiui, pt-BR, trūksta vertimo rakto, svelte-i18n iškart pereina prie numatytosios lokalės, užuot pirmiausia patikrinęs pirminę lokalę pt.

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',
});

Visą palaikomų sistemų sąrašą ir 75 integruotas grandines rasite mūsų atsarginių lokalių vadove. Learn more →

Dažnai užduodami klausimai