Skip to main content

SvelteKit i18n: ръководство за настройване на интернационализацията

От нулата до многоезично приложение: настройте svelte-i18n във Вашето SvelteKit приложение с формата за съобщения ICU, маршрутизиране по езикови версии и интелигентни резервни вериги.

1

Инсталирайте svelte-i18n

svelte-i18n е стандартната библиотека за интернационализация на Svelte и SvelteKit. Тя предлага реактивни хранилища, поддръжка на ICU MessageFormat и отложено зареждане на езиковите версии без допълнително настройване.

svelte-i18n използва ICU MessageFormat за множествено число и променливи — същия стандарт, който използват FormatJS/react-intl. Ако преминавате от React, синтаксисът на съобщенията ще Ви бъде познат.
Terminal
npm install svelte-i18n
2

Настройте svelte-i18n

Създайте конфигурационен файл за i18n, който регистрира езиковите версии чрез функции за динамично импортиране. svelte-i18n ще извлече съобщенията за дадена езикова версия едва когато тя бъде активирана.

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 в +layout.svelte, преди да се визуализира който и да е компонент. Ако вместо преводи се показват необработени ключове като 'nav.home', конфигурацията не е импортирана достатъчно рано.

Интегриране в оформлението на SvelteKit

Импортирайте конфигурацията за i18n в основното оформление и управлявайте визуализирането чрез хранилището $isLoading. Така предотвратявате краткото показване на непреведени ключове, докато данните за езиковата версия се зареждат асинхронно.

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}

Маршрутизиране по езикови версии в SvelteKit

За подходящи за SEO URL адреси като /en/about и /de/about използвайте параметър на маршрута [lang]. Задайте езиковата версия на svelte-i18n във функцията load на оформлението въз основа на параметъра от 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}

Формат на преводните файлове

Създайте по един JSON файл за всяка езикова версия. svelte-i18n поддържа вложени ключове и синтаксиса на ICU MessageFormat за множествено число, променливи и изрази 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}}"
  }
}
Наименувайте ключовете според това, което описват, а не според мястото им в интерфейса: 'cart.itemCount' е по-добър от 'homepageCartLabel'. Ключовете трябва да останат приложими и след промени в дизайна на интерфейса.
3

Използвайте преводите в компоненти

Импортирайте хранилището $_ (или $format) от svelte-i18n и го използвайте във Вашите Svelte шаблони. Хранилището е реактивно — при смяна на езиковата версия всички преведени низове се обновяват автоматично.

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>
$_ е хранилище на Svelte — трябва да използвате префикса $ в шаблоните. Ако напишете _('key') без знака за долар, ще получите обекта на хранилището, а не преведения низ.

Смяна на езика

Създайте селектор за език, свързан с хранилището $locale. При промяна на стойността svelte-i18n зарежда съобщенията за новата езикова версия и реактивно обновява всички преведени низове.

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

Обработвайте множествено число с ICU MessageFormat

svelte-i18n използва ICU MessageFormat за множествено число — международния стандарт, който обработва всички категории на CLDR. Арабският има 6 форми, руският — 4, а японският — 1. Дефинирайте формите, необходими за целевите Ви езици, и svelte-i18n автоматично ще избере правилната.

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 {#個のアイテム}}"
}
Никога не задавайте директно в компонентите логика за единствено и множествено число. Езици като френския третират 0 като единствено число. Арабският, руският и полският имат форми за множествено число, които не съществуват в английския. Оставете обработката на синтаксиса за множествено число на ICU.

Интелигентни резервни езикови версии със svelte-i18n-locale-chain

Когато липсва ключ, svelte-i18n преминава директно към fallbackLocale — няма междинна резервна версия. Така потребител с pt-BR вижда английски текст вместо напълно подходящия превод за pt-PT. svelte-i18n-locale-chain решава проблема чрез интелигентни резервни вериги, които рекурсивно обединяват съобщенията от регионалните варианти.

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 управлява вътрешно цялото зареждане на съобщения. Не използвайте едновременно с него функцията register() на svelte-i18n — initLocaleChain се грижи за регистрирането, зареждането и рекурсивното обединяване.

Автоматизирайте преводите

След като завършите настройването на i18n, преведете файловете за езиковите версии с ИИ. Във Вашата IDE помолете асистента си с ИИ да преведе изходния файл или използвайте i18n Agent CLI във Вашия 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
Превеждайте поетапно — когато добавите нови ключове към изходния файл, преведете само разликите, вместо да създавате отново всички файлове. Така запазвате преводите, прегледани от човек.

Автоматизирайте контрола на качеството на преводите

Откривайте липсващи ключове и повредени заместващи параметри с i18n-validate, преди да достигнат до потребителите. Тествайте интерфейса си с псевдопреводи чрез i18n-pseudo, преди да получите реалните преводи.

Често срещани проблеми

Смесване на езикови версии при SSR в SvelteKit

Хранилищата на svelte-i18n са единични екземпляри. При SSR в SvelteKit едновременните заявки споделят едно и също хранилище — езиковата версия на един потребител може да попадне в отговора за друг. Решение: извикайте locale.set() в hook-а handle или във функцията load на оформлението, така че всяка заявка да получи правилния езиков контекст.

Използване на register() със svelte-i18n-locale-chain

Не използвайте функцията register() на svelte-i18n, ако използвате svelte-i18n-locale-chain. initLocaleChain управлява вътрешно цялото зареждане на съобщения. Съвместната им употреба води до дублирано или противоречиво зареждане.

Грешките в синтаксиса на ICU не се съобщават

Несъответстваща фигурна скоба или липсваща категория за множествено число в низовете на ICU MessageFormat води до грешка без съобщение — вместо форматирания резултат се показва необработеният низ. Проверявайте синтаксиса на ICU във Вашия CI пайплайн.

Кратко показване на непреведено съдържание

Ако визуализирате компонентите, преди преводите да са заредени, потребителите виждат необработени ключове. Управлявайте оформлението си с {#if $isLoading}...{:else}...{/if}, за да показвате състояние на зареждане, докато съобщенията станат готови.

Препоръчителна файлова структура

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

Изпробвайте i18n Agent сега

Пуснете тук Вашия файл за превод

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

или натиснете, за да изберете файл

Целеви езици

Не се изисква регистрацияНезабавна оценка

Резервни езикови версии със svelte-i18n-locale-chain

Когато липсва ключ за превод в регионална езикова версия като pt-BR, svelte-i18n преминава директно към езиковата версия по подразбиране, вместо първо да провери родителската версия 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',
});

Вижте нашето ръководство за резервни езикови версии за пълния списък с поддържани софтуерни рамки и 75 вградени вериги. Learn more →

Често задавани въпроси