Skip to main content

SvelteKit i18n: Gabay sa Setup ng Internationalization

Mula zero hanggang multilingual: i-set up ang svelte-i18n sa inyong SvelteKit app gamit ang ICU message format, locale-based routing, at smart fallback chain.

1

I-install ang svelte-i18n

Ang svelte-i18n ang standard internationalization library para sa Svelte at SvelteKit. Nagbibigay ito ng reactive store, suporta sa ICU MessageFormat, at lazy locale loading out of the box.

Gumagamit ang svelte-i18n ng ICU MessageFormat para sa plural at variable — ang parehong standard na ginagamit ng FormatJS/react-intl. Kung galing kayo sa React, magiging pamilyar ang message syntax.
Terminal
npm install svelte-i18n
2

I-configure ang svelte-i18n

Gumawa ng i18n configuration file na nirerehistro ang inyong mga locale gamit ang lazy-loaded import function. Kukunin lang ng svelte-i18n ang mga message ng isang locale kapag na-activate ang locale na iyon.

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
});
Dapat ninyong i-import ang i18n config file sa +layout.svelte bago mag-render ang anumang component. Kung lumalabas ang mga pagsasalin bilang raw key tulad ng 'nav.home', hindi na-import nang sapat na maaga ang config.

Integrasyon ng Layout sa SvelteKit

I-import ang i18n config sa root layout at i-guard ang pag-render gamit ang $isLoading store. Pinipigilan nito ang pag-flash ng untranslated key habang naglo-load nang asynchronous ang locale data.

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}

Locale-Based Routing sa SvelteKit

Para sa SEO-friendly na URL tulad ng /en/about at /de/about, gumamit ng [lang] route parameter. Itakda ang svelte-i18n locale sa load function ng layout batay sa 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}

Format ng Translation File

Gumawa ng isang JSON file para sa bawat locale. Sinusuportahan ng svelte-i18n ang nested key at ICU MessageFormat syntax para sa plural, variable, at select expression.

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}}"
  }
}
Pangalanan ang mga key ayon sa inilalarawan nila, hindi ayon sa kung saan sila lumalabas: mas mabuti ang 'cart.itemCount' kaysa 'homepageCartLabel'. Dapat tumagal ang mga key kahit magbago ang UI design.
3

Gamitin ang Mga Pagsasalin sa Mga Component

I-import ang $_ store (o $format) mula sa svelte-i18n at gamitin ito sa inyong Svelte template. Reactive ang store — kapag nagbago ang locale, awtomatikong mag-a-update ang lahat ng isinaling string.

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>
Ang $_ ay isang Svelte store — dapat ninyong gamitin ang $ prefix sa template. Ang pagsulat ng _('key') nang walang dollar sign ay nagbabalik ng store object, hindi ng isinaling string.

Pagpapalit ng Wika

Bumuo ng language selector na naka-bind sa $locale store. Kapag nagbago ang value, ilo-load ng svelte-i18n ang mga message ng bagong locale at reactive na ia-update ang lahat ng isinaling string.

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

Pangasiwaan ang Maramihan gamit ang ICU MessageFormat

Gumagamit ang svelte-i18n ng ICU MessageFormat para sa pluralization—isang internasyonal na pamantayan na humahawak sa lahat ng CLDR plural categories. May 6 na anyo ang Arabic, 4 ang Russian, at 1 ang Japanese. Ideklara ang mga anyong kailangan ng inyong target na mga wika at awtomatikong pipiliin ng svelte-i18n ang tama.

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 {#個のアイテム}}"
}
Huwag kailanman mag-hardcode ng singular/plural logic sa inyong mga component. Itinuturing ng mga wikang tulad ng French na singular ang 0. May mga anyo ng plural ang Arabic, Russian, at Polish na wala sa English. Hayaan ninyong ang ICU plural syntax ang humawak nito.

Mas Matalinong Locale Fallback gamit ang svelte-i18n-locale-chain

Kapag may nawawalang key, diretso lang magfa-fallback ang svelte-i18n sa fallbackLocale—walang intermediate fallback. Dahil dito, makakakita ang pt-BR user ng English sa halip na maayos na pt-PT translations. Inaayos ito ng svelte-i18n-locale-chain gamit ang smart fallback chains na nagde-deep-merge ng mga message mula sa mga regional variant.

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
Pinamamahalaan ng svelte-i18n-locale-chain ang lahat ng paglo-load ng message sa loob nito. Huwag ninyong gamitin ang register() function ng svelte-i18n kasabay nito—ang initLocaleChain ang humahawak sa registration, loading, at deep-merging.

I-automate ang Pagsasalin

Kapag kumpleto na ang inyong i18n setup, isalin ang inyong mga locale file gamit ang AI. Sa inyong IDE, hilingin sa inyong AI assistant na isalin ang source file, o gamitin ang i18n Agent CLI sa inyong 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
Isalin nang paunti-unti—kapag nagdagdag kayo ng mga bagong key sa inyong source file, isalin lamang ang diff sa halip na i-regenerate ang lahat ng file. Pinapanatili nito ang anumang pagsasaling na-review na ng tao.

I-automate ang Kalidad ng Pagsasalin

Matukoy ang mga nawawalang key at sirang placeholder bago ma-ship gamit ang i18n-validate. Subukan ang inyong UI gamit ang pseudo-translations sa pamamagitan ng i18n-pseudo bago dumating ang mga tunay na pagsasalin.

Mga Karaniwang Pitfall

SSR Locale Bleed sa SvelteKit

Singleton ang mga store ng svelte-i18n. Sa SvelteKit SSR, maaaring mag-share ang mga sabayang request ng iisang store—maaaring mapunta ang locale ng isang user sa response ng iba. Ayos: tawagin ang locale.set() sa handle hook o layout load function para makuha ng bawat request ang tamang locale context.

Paggamit ng register() kasama ang svelte-i18n-locale-chain

Huwag ninyong gamitin ang register() function ng svelte-i18n kung gumagamit kayo ng svelte-i18n-locale-chain. Ang initLocaleChain ang humahawak sa lahat ng paglo-load ng message sa loob nito. Ang paghahalo ng dalawa ay nagdudulot ng duplicate o nagkakasalungatang paglo-load ng message.

Nabibigo nang Tahimik ang Mga ICU Syntax Error

Ang hindi nagtutugmang brace o nawawalang plural category sa mga string ng ICU MessageFormat ay nagdudulot ng silent failures—ipinapakita ang raw message string sa halip na ang formatted output. I-validate ang ICU syntax sa inyong CI pipeline.

Panandaliang paglitaw ng hindi pa naisaling nilalaman

Kung nirere-render ninyo ang mga component bago matapos ang paglo-load ng mga pagsasalin, makikita ng mga user ang mga raw key. I-guard ang inyong layout gamit ang {#if $isLoading}...{:else}...{/if} para magpakita ng loading state hanggang handa na ang mga message.

Inirerekomendang File Structure

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

Subukan ang i18n Agent Ngayon

I-drop dito ang inyong translation file

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

o i-click para mag-browse

Mga target language

Hindi kailangan ang signupInstant na estimate

Locale Fallback gamit ang svelte-i18n-locale-chain

Kapag may nawawalang translation key sa isang regional locale tulad ng pt-BR, diretso tumatalon ang svelte-i18n sa default locale sa halip na tingnan muna ang parent locale na 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',
});

Tingnan ang aming Locale Fallback Guide para sa kumpletong listahan ng sinusuportahang framework at 75 built-in chain. Learn more →

Mga Madalas Itanong