Skip to main content

SvelteKit i18n: ghid de configurare a internaționalizării

De la zero la o aplicație multilingvă: configurați svelte-i18n în aplicația SvelteKit cu formatul mesajelor ICU, rutare în funcție de setarea regională și lanțuri inteligente de rezervă.

1

Instalați svelte-i18n

svelte-i18n este biblioteca standard de internaționalizare pentru Svelte și SvelteKit. Aceasta oferă store-uri reactive, compatibilitate cu ICU MessageFormat și încărcarea la cerere a setărilor regionale.

svelte-i18n folosește ICU MessageFormat pentru pluraluri și variabile — același standard utilizat de FormatJS/react-intl. Dacă veniți din ecosistemul React, sintaxa mesajelor vă va fi familiară.
Terminal
npm install svelte-i18n
2

Configurați svelte-i18n

Creați un fișier de configurare i18n care înregistrează setările regionale folosind funcții de import cu încărcare la cerere. svelte-i18n va prelua mesajele unei setări regionale numai atunci când aceasta este activată.

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
});
Trebuie să importați fișierul de configurare i18n în +layout.svelte înainte de randarea oricărei componente. Dacă traducerile afișează chei neprelucrate precum 'nav.home', configurația nu a fost importată suficient de devreme.

Integrarea cu aspectul SvelteKit

Importați configurația i18n în aspectul rădăcină și condiționați randarea folosind store-ul $isLoading. Astfel evitați afișarea temporară a cheilor netraduse în timpul încărcării asincrone a datelor setării regionale.

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}

Rutare în funcție de setarea regională în SvelteKit

Pentru adrese URL optimizate pentru SEO, precum /en/about și /de/about, folosiți parametrul de traseu [lang]. Setați setarea regională svelte-i18n în funcția load a aspectului, pe baza parametrului din adresa URL.

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}

Formatul fișierelor de traducere

Creați câte un fișier JSON pentru fiecare setare regională. svelte-i18n acceptă chei imbricate și sintaxa ICU MessageFormat pentru pluraluri, variabile și expresii select.

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}}"
  }
}
Denumiți cheile după ceea ce descriu, nu după locul în care apar: 'cart.itemCount' este mai potrivit decât 'homepageCartLabel'. Cheile trebuie să rămână valabile după reproiectarea interfeței.
3

Folosiți traducerile în componente

Importați store-ul $_ (sau $format) din svelte-i18n și folosiți-l în șabloanele Svelte. Store-ul este reactiv — când se schimbă setarea regională, toate șirurile traduse se actualizează automat.

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>
$_ este un store Svelte — trebuie să folosiți prefixul $ în șabloane. Dacă scrieți _('key') fără semnul dolarului, obțineți obiectul store, nu șirul tradus.

Schimbarea limbii

Creați un selector de limbă conectat la store-ul $locale. Când se schimbă valoarea, svelte-i18n încarcă mesajele noii setări regionale și actualizează reactiv toate șirurile traduse.

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

Gestionați pluralurile cu ICU MessageFormat

svelte-i18n folosește ICU MessageFormat pentru pluralizare — standardul internațional care gestionează toate categoriile de plural CLDR. Araba are 6 forme, rusa are 4, iar japoneza are 1. Definiți formele necesare limbilor vizate, iar svelte-i18n o selectează automat pe cea corectă.

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 {#個のアイテム}}"
}
Nu introduceți niciodată direct în componente logica pentru singular și plural. Limbi precum franceza tratează 0 ca singular. Araba, rusa și poloneza au forme de plural care nu există în engleză. Lăsați sintaxa de plural ICU să gestioneze aceste reguli.

Mecanisme inteligente de rezervă pentru setările regionale cu svelte-i18n-locale-chain

svelte-i18n recurge direct la fallbackLocale atunci când lipsește o cheie — nu există un nivel intermediar de rezervă. Un utilizator pt-BR vede textul în engleză, deși există traduceri pt-PT perfect adecvate. svelte-i18n-locale-chain rezolvă problema prin lanțuri inteligente de rezervă care îmbină profund mesajele variantelor regionale.

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 gestionează intern întreaga încărcare a mesajelor. Nu folosiți simultan funcția register() din svelte-i18n — initLocaleChain se ocupă de înregistrare, încărcare și îmbinare profundă.

Automatizați traducerile

După finalizarea configurării i18n, traduceți fișierele de localizare cu ajutorul IA. În mediul IDE, solicitați-i asistentului IA să traducă fișierul-sursă sau folosiți interfața CLI i18n Agent în fluxul CI/CD.

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
Traduceți incremental — când adăugați chei noi în fișierul-sursă, traduceți numai diferențele, în loc să regenerați toate fișierele. Astfel păstrați traducerile verificate de o persoană.

Automatizați controlul calității traducerilor

Identificați cheile lipsă și substituenții nevalizi înainte de lansare cu i18n-validate. Testați interfața folosind pseudotraduceri cu i18n-pseudo înainte de a primi traducerile reale.

Capcane frecvente

Propagarea setării regionale între cereri SSR în SvelteKit

Store-urile svelte-i18n sunt instanțe unice. În SSR cu SvelteKit, cererile simultane folosesc același store — setarea regională a unui utilizator se poate propaga în răspunsul altuia. Soluție: apelați locale.set() în hook-ul handle sau în funcția load a aspectului, astfel încât fiecare cerere să primească setarea regională corectă.

Utilizarea register() cu svelte-i18n-locale-chain

Nu folosiți funcția register() din svelte-i18n dacă utilizați svelte-i18n-locale-chain. initLocaleChain gestionează intern întreaga încărcare a mesajelor. Combinarea celor două produce încărcări duplicate sau contradictorii ale mesajelor.

Erorile de sintaxă ICU nu sunt semnalate

O acoladă fără pereche sau lipsa unei categorii de plural din șirurile ICU MessageFormat produce erori nesemnalate — în locul rezultatului formatat este afișat șirul brut al mesajului. Validați sintaxa ICU în fluxul CI.

Afișarea temporară a conținutului netradus

Dacă randați componentele înainte de finalizarea încărcării traducerilor, utilizatorii văd cheile neprelucrate. Protejați aspectul cu {#if $isLoading}...{:else}...{/if} pentru a afișa o stare de încărcare până când mesajele sunt pregătite.

Structura recomandată a fișierelor

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

Încercați acum i18n Agent

Plasați aici fișierul de traducere

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

sau faceți clic pentru a-l selecta

Limbi țintă

Nu este necesară înregistrareaEstimare instantanee

Mecanism de rezervă pentru setările regionale cu svelte-i18n-locale-chain

Când lipsește o cheie de traducere dintr-o setare regională precum pt-BR, svelte-i18n trece direct la setarea regională implicită, fără a verifica mai întâi setarea regională părinte 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',
});

Consultați Ghidul mecanismelor de rezervă pentru setările regionale pentru lista completă a cadrelor acceptate și a celor 75 de lanțuri integrate. Learn more →

Întrebări frecvente