Sveltia I18n

An internationalization (i18n) library for Svelte applications that uses Unicode MessageFormat 2 (MF2) to format messages.

#i18n #internationalization #l10n #localization #messageformat #svelte #translation

Download

Sveltia I18n

An internationalization (i18n) library for Svelte applications. Heavily inspired by svelte-i18n, but powered by Svelte 5 Runes and the messageformat library for formatting messages using Unicode MessageFormat 2 (MF2), which supports complex pluralization and selection patterns in addition to simple variable interpolation.

Installation
Usage
SvelteKit usage
API
Message Format
Compatibility with svelte-i18n
- Functions
- Key differences
Examples

Installation

pnpm add @sveltia/i18n

Usage

import { _, addMessages, init, locale, register, waitLocale } from '@sveltia/i18n';

SvelteKit usage

Async loading with SSR

// src/lib/i18n.js
import { register, init } from '@sveltia/i18n';

register('en-US', () => import('./locales/en-US.yaml?raw').then((m) => parseYaml(m.default)));
register('fr', () => import('./locales/fr.yaml?raw').then((m) => parseYaml(m.default)));

init({ fallbackLocale: 'en-US' });

// src/routes/+layout.js
import { browser } from '$app/environment';
import '$lib/i18n'; // initialize
import { locale, waitLocale, getLocaleFromNavigator } from '@sveltia/i18n';

export const load = async () => {
  if (browser) await locale.set(getLocaleFromNavigator());
  await waitLocale();
};

Server-side locale via `Accept-Language`

Read the request header in a server hook and set the locale before rendering:

// src/hooks.server.js
import { locale } from '@sveltia/i18n';

export const handle = async ({ event, resolve }) => {
  const lang = event.request.headers.get('accept-language')?.split(',')[0];
  if (lang) await locale.set(lang);
  return resolve(event);
};

Client-side locale detection

For client-only apps (no SSR), detect the locale directly from the browser environment and call locale.set() in onMount or in a +layout.js load function guarded by browser:

// src/routes/+layout.js
import { browser } from '$app/environment';
import '$lib/i18n'; // initialize
import {
  locale,
  waitLocale,
  getLocaleFromNavigator,
  getLocaleFromQueryString,
} from '@sveltia/i18n';

export const load = async () => {
  if (browser) {
    // Pick the first available source: ?lang= query param, then browser preference
    const detected = getLocaleFromQueryString('lang') ?? getLocaleFromNavigator();
    await locale.set(detected ?? 'en-US');
  }
  await waitLocale();
};

You can combine any of the getLocaleFrom* helpers in priority order:

Helper	Source
`getLocaleFromNavigator()`	`navigator.languages[0]` / `navigator.language`
`getLocaleFromQueryString('lang')`	`?lang=fr` URL parameter
`getLocaleFromPathname(/^\/([\w-]+)\//)`	`/fr/page` path prefix
`getLocaleFromHostname(/^([\w-]+)\./)`	`fr.example.com` subdomain
`getLocaleFromHash('lang')`	`#lang=fr` hash parameter

API

State

`locales`

A reactive array of all registered locale codes.

import { locales } from '@sveltia/i18n';
// ['en-US', 'fr', 'ja']

`dictionary`

A reactive record of all registered messages, keyed by locale code then message key. Values are Intl.MessageFormat instances. Useful for advanced inspection; prefer format/_ for normal use.

`isLoading()`

Returns true when a locale has been set but its messages have not yet been loaded. Useful to show a loading indicator or guard rendering until resources are ready.

import { isLoading } from '@sveltia/i18n';
if (isLoading()) return; // messages still loading

`isRTL()`

Returns true when the current locale is written right-to-left (e.g. Arabic, Hebrew, Persian). Reactive: re-evaluates automatically whenever the locale changes.

import { isRTL } from '@sveltia/i18n';
if (isRTL()) console.log('RTL layout active');

In a Svelte template:

<div dir={isRTL() ? 'rtl' : 'ltr'}>
  {_('content')}
</div>

Locale

`locale`

A reactive object representing the current locale.

locale.current; // → 'en-US'
await locale.set('fr'); // switch to French, triggers any registered loader, updates <html lang>

locale.set(value) returns a Promise<void> that resolves once any loader registered for the new locale has finished loading. It also keeps document.documentElement.lang and document.documentElement.dir (ltr/rtl) in sync automatically.

Locale negotiation: if the requested value is not in the registered locales list, locale.set() tries to find the best match by language subtag before falling back to the original value. For example, if en-US is registered and the user’s browser reports en-CA, locale.current is set to en-US.

// locales registered: ['en-US', 'fr', 'ja']
await locale.set('en-CA'); // locale.current → 'en-US'
await locale.set('zh-TW'); // no match → locale.current stays 'zh-TW'

`getLocaleFromNavigator()`

Returns the user’s preferred locale from the browser (navigator.languages[0] or navigator.language).

import { getLocaleFromNavigator } from '@sveltia/i18n';
const lang = getLocaleFromNavigator(); // e.g. 'ja'

`getLocaleFromHostname(pattern)`

Matches location.hostname against a RegExp and returns capture group 1.

import { getLocaleFromHostname } from '@sveltia/i18n';
// URL: https://fr.example.com/
getLocaleFromHostname(/^(.*?)\./); // → 'fr'

`getLocaleFromPathname(pattern)`

Matches location.pathname against a RegExp and returns capture group 1.

import { getLocaleFromPathname } from '@sveltia/i18n';
// URL: https://example.com/en-US/about
getLocaleFromPathname(/^\/(\w[\w-]*)\//); // → 'en-US'

`getLocaleFromQueryString(key)`

Reads a locale code from a URL query string parameter.

import { getLocaleFromQueryString } from '@sveltia/i18n';
// URL: https://example.com/?lang=ja
getLocaleFromQueryString('lang'); // → 'ja'

`getLocaleFromHash(key)`

Reads a locale code from a key=value pair in location.hash.

import { getLocaleFromHash } from '@sveltia/i18n';
// URL: https://example.com/#lang=fr
getLocaleFromHash('lang'); // → 'fr'

Configuration

`init(options)`

Configures the library. All options except fallbackLocale are optional.

Option	Type	Description
`fallbackLocale`	`string`	Locale used when a key is missing from the current locale.
`initialLocale`	`string`	Locale to activate immediately.
`formats`	`{ number?, date?, time? }`	Custom named formats for `number()`, `date()`, and `time()`.
`handleMissingMessage`	`(key, locale, defaultValue) => string \| void`	Called when a key is not found. Return a string to replace the fallback, or `undefined` to continue with the default behaviour.

import { getLocaleFromNavigator, init } from '@sveltia/i18n';

init({
  fallbackLocale: 'en-US',
  initialLocale: getLocaleFromNavigator(),
  formats: {
    number: { EUR: { style: 'currency', currency: 'EUR' } },
  },
  handleMissingMessage: (key, locale) => {
    console.warn(`Missing message: ${key} (${locale})`);
  },
});

Loader

`register(localeCode, loader)`

Registers an async loader function for a locale. The loader is called the first time waitLocale(localeCode) is invoked for that locale, and its result is passed to addMessages. (locale.set() triggers loading by calling waitLocale() internally.) Calling register() again for the same locale invalidates the cached promise so the new loader is picked up on the next waitLocale() call.

import { register, waitLocale, locale } from '@sveltia/i18n';

register('en-US', () => import('./locales/en-US.yaml?raw').then((m) => parseYaml(m.default)));
register('fr', () => import('./locales/fr.yaml?raw').then((m) => parseYaml(m.default)));

// In a SvelteKit +layout.js load function:
export const load = async () => {
  locale.set('en-US');
  await waitLocale();
};

`waitLocale(localeCode?)`

Executes the loader registered for localeCode (defaults to locale.current) and returns a Promise<void> that resolves when the messages are loaded. Repeated calls for the same locale return the same promise (deduplication). Safe to call even when no loader is registered — it resolves immediately. If the loader rejects, the cached promise is cleared so the next waitLocale() call will retry.

await waitLocale('fr'); // load French
await waitLocale(); // load the current locale

Messages

`addMessages(localeCode, ...maps)`

Registers one or more message maps for a locale. Values must be valid MF2 message strings. Maps may be flat (dot-separated keys) or nested objects — both are normalised to dot-separated keys. Multiple maps are merged in order, matching svelte-i18n’s variadic signature.

import { addMessages } from '@sveltia/i18n';

// Flat
addMessages('en-US', {
  'field.name': 'Name',
  'field.birth': 'Date of birth',
});

// Nested (equivalent)
addMessages('en-US', {
  field: {
    name: 'Name',
    birth: 'Date of birth',
  },
  notifications: `
    .input {$count :integer}
    .match $count
    0   {{You have no notifications.}}
    one {{You have {$count} notification.}}
    *   {{You have {$count} notifications.}}
  `,
});

// Multiple maps merged in one call
addMessages('en-US', { 'field.name': 'Name' }, { 'field.birth': 'Date of birth' });

_('field.name'); // → 'Name'

Formatting

`format(key, options?)` / `_(key, options?)` / `t(key, options?)`

Formats a message by key. _ and t are aliases for format.

Supports two call signatures (matching svelte-i18n):

format(id, options?) — key as first argument
format({ id, values?, locale?, default? }) — options object only

Option	Type	Description
`values`	`Record<string, any>`	Variables to interpolate into the message.
`locale`	`string`	Override the active locale for this call only. If the key is not found in the override locale, the lookup still falls back to `fallbackLocale`.
`default`	`string`	Fallback string if the key is not found in any locale.

import { _, t } from '@sveltia/i18n';

_('hello', { values: { name: 'Alice' } }); // → 'Hello, Alice!'
_('notifications', { values: { count: 3 } }); // → 'You have 3 notifications.'
_('missing.key', { default: 'Not found' }); // → 'Not found'
_('missing.key'); // → 'missing.key'

// Per-call locale override (does not change locale.current)
_('hello', { locale: 'fr', values: { name: 'Alice' } }); // → 'Bonjour, Alice!'

// Object-first signature (svelte-i18n compatible)
_({ id: 'hello', values: { name: 'Alice' } }); // → 'Hello, Alice!'

// svelte-i18n-style alias
t('hello'); // → 'Hello!'

`json(prefix, options?)`

Returns a flat object of formatted strings for all message keys under the given prefix. Equivalent to svelte-i18n’s $json(). Useful for iterating over a group of related messages without knowing every key name.

import { json } from '@sveltia/i18n';

// Locale file has: nav.home, nav.about, nav.contact
json('nav'); // → { home: 'Home', about: 'About', contact: 'Contact' }
json('unknown'); // → undefined

When the active locale has no messages, json() falls back to the fallbackLocale dictionary, matching the same fallback behaviour as format().

In a Svelte template:

{#each Object.entries(json('nav') ?? {}) as [key, label]}
  <a href="/{key}">{label}</a>
{/each}

Options:

Option	Type	Description
`locale`	`string`	Override the active locale for this call

Date, time & number

`date(value, options?)`

Formats a Date as a localized date string. Equivalent to svelte-i18n’s $date().

Options accept any Intl.DateTimeFormatOptions plus:

Option	Type	Description
`locale`	`string`	Override the active locale for this call.
`format`	`string`	A named format: `short`, `medium`, `long`, `full`, or a custom name defined in `init({ formats })`.

import { date } from '@sveltia/i18n';

date(new Date('2026-01-23')); // → '1/23/2026'
date(new Date('2026-01-23'), { format: 'long' }); // → 'January 23, 2026'
date(new Date('2026-01-23'), { locale: 'fr-FR', format: 'long' }); // → '23 janvier 2026'

`time(value, options?)`

Formats a Date as a localized time string. Equivalent to svelte-i18n’s $time().

Options accept any Intl.DateTimeFormatOptions plus locale and format (same named formats as date() but from the time set: short, medium, long, full).

import { time } from '@sveltia/i18n';

time(new Date('2026-01-23T15:04:00')); // → '3:04 PM'
time(new Date('2026-01-23T15:04:00'), { format: 'medium' }); // → '3:04:00 PM'

`number(value, options?)`

Formats a number as a localized string. Equivalent to svelte-i18n’s $number().

Options accept any Intl.NumberFormatOptions plus:

Option	Type	Description
`locale`	`string`	Override the active locale for this call.
`format`	`string`	A named format: `currency`, `percent`, `scientific`, `engineering`, `compactLong`, `compactShort`, or a custom name defined in `init({ formats })`.

import { number } from '@sveltia/i18n';

number(1234567); // → '1,234,567'
number(0.42, { format: 'percent' }); // → '42%'
number(9.99, { style: 'currency', currency: 'USD' }); // → '$9.99'

// Custom named format defined in init()
// init({ formats: { number: { EUR: { style: 'currency', currency: 'EUR' } } } })
number(9.99, { format: 'EUR' }); // → '€9.99'

Message Format

Locale files use MF2 syntax. Single-pattern messages can be written as plain YAML strings; multi-pattern messages use YAML block scalars.

Simple interpolation

# en-US.yaml
greeting: 'Hello, {$name}!'
farewell: 'Goodbye, {$name}. See you on {$date :date length=long}.'

Pluralization

English has two plural forms (one / *):

# en-US.yaml
notifications: |
  .input {$count :integer}
  .match $count
    0   {{You have no notifications.}}
    one {{You have {$count} notification.}}
    *   {{You have {$count} notifications.}}

French treats 0 as singular:

# fr.yaml
notifications: |
  .input {$count :integer}
  .match $count
    0   {{Vous n’avez aucune notification.}}
    one {{Vous avez {$count} notification.}}
    *   {{Vous avez {$count} notifications.}}

Polish has four plural forms — one, few (2–4, except teens), many (5+, teens), and * (fractions) — making it a good stress-test for pluralization logic:

# pl.yaml
notifications: |
  .input {$count :integer}
  .match $count
    0    {{Nie masz żadnych powiadomień.}}
    one  {{Masz {$count} powiadomienie.}}
    few  {{Masz {$count} powiadomienia.}}
    many {{Masz {$count} powiadomień.}}
    *    {{Masz {$count} powiadomienia.}}

items: |
  .input {$count :integer}
  .match $count
    0    {{Nie znaleziono żadnych elementów.}}
    one  {{Znaleziono {$count} element.}}
    few  {{Znaleziono {$count} elementy.}}
    many {{Znaleziono {$count} elementów.}}
    *    {{Znaleziono {$count} elementu.}}

Arabic has six plural forms (zero, one, two, few, many, *):

# ar.yaml
notifications: |
  .input {$count :integer}
  .match $count
    0    {{ليس لديك أي إشعارات.}}
    one  {{لديك إشعار واحد.}}
    two  {{لديك إشعاران.}}
    few  {{لديك {$count} إشعارات.}}
    many {{لديك {$count} إشعارًا.}}
    *    {{لديك {$count} إشعار.}}

Ordinal numbers

English ordinal suffixes (1st, 2nd, 3rd, 4th, …):

# en-US.yaml
ranking: |
  .input {$rank :number select=ordinal}
  .match $rank
    one {{The team is ranked {$rank}st.}}
    two {{The team is ranked {$rank}nd.}}
    few {{The team is ranked {$rank}rd.}}
    *   {{The team is ranked {$rank}th.}}

Gender selection

A single gender variable:

# en-US.yaml
welcome: |
  .input {$gender :string}
  .match $gender
    female {{Welcome, Ms. {$name}.}}
    male   {{Welcome, Mr. {$name}.}}
    *      {{Welcome, {$name}.}}

Multiple selectors (gender × guest count):

# en-US.yaml
party: |
  .input {$hostGender :string}
  .input {$guestCount :number}
  .match $hostGender $guestCount
    female 0 {{{$hostName} does not give a party.}}
    female 1 {{{$hostName} invites {$guestName} to her party.}}
    female * {{{$hostName} invites {$guestCount} people, including {$guestName}, to her party.}}
    male   0 {{{$hostName} does not give a party.}}
    male   1 {{{$hostName} invites {$guestName} to his party.}}
    male   * {{{$hostName} invites {$guestCount} people, including {$guestName}, to his party.}}
    *      0 {{{$hostName} does not give a party.}}
    *      1 {{{$hostName} invites {$guestName} to their party.}}
    *      * {{{$hostName} invites {$guestCount} people, including {$guestName}, to their party.}}

Number formatting

# en-US.yaml
price: 'Price: {$amount :currency currency=USD}.'
progress: 'Progress: {$ratio :percent}.'
decimal: 'Value: {$num :number minimumFractionDigits=2}.'
signed: 'Change: {$num :number signDisplay=always}.'
id: 'ID: {$num :number minimumIntegerDigits=4}.'

Date and time

# en-US.yaml
today: 'Today is {$date :date}.'
date-short: 'Short date: {$date :date length=short}.'
date-long: 'Long date: {$date :date fields=|month-day-weekday| length=long}.'
datetime: 'Appointment: {$date :datetime}.'
time: 'The time is {$time :time}.'
time-precise: 'Precise time: {$time :time precision=second}.'

Built-in MF2 functions

Built-in MF2 functions available via DraftFunctions:

Function	Purpose	Example
`:number`	Decimal number formatting	`{$n :number minimumFractionDigits=2}`
`:integer`	Integer (no decimals) + plural selection	`{$n :integer}`
`:percent`	Percentage (multiplies by 100)	`{$r :percent}`
`:currency`	Currency formatting	`{$n :currency currency=USD}`
`:date`	Date-only formatting	`{$d :date length=short}`
`:time`	Time-only formatting	`{$t :time precision=second}`
`:datetime`	Date + time formatting	`{$d :datetime}`
`:string`	String selector	`{$s :string}`

Compatibility with svelte-i18n

Sveltia I18n is designed to be a modern alternative to svelte-i18n. The table below summarises the mapping between the two APIs.

Functions

svelte-i18n	Sveltia I18n	Notes
`$_()` / `$t()` / `$format()`	`_()` / `t()` / `format()`	Same two signatures: `(id, opts?)` and `({ id, values?, locale?, default? })`. Not a Svelte store; call directly.
`$json()`	`json()`	Identical behaviour.
`$date()`	`date()`	Identical signature and named formats (`short`, `medium`, `long`, `full`).
`$time()`	`time()`	Identical signature and named formats.
`$number()`	`number()`	Identical signature and named formats (`currency`, `percent`, `scientific`, `engineering`, `compactLong`, `compactShort`).
`$locale`	`locale` / `locale.current`	Reactive object instead of a Svelte store. Use `locale.current` to read and `locale.set(value)` to write.
`$isLoading`	`isLoading()`	Function instead of a store.
N/A	`isRTL()`	Returns `true` when the current locale is RTL. No svelte-i18n equivalent.
`$locales`	`locales`	Reactive array instead of a store.
`$dictionary`	`dictionary`	Reactive object instead of a store.
`init()`	`init()`	Identical option names. `initialLocale` and `formats` are supported.
`addMessages()`	`addMessages()`	Variadic (`...maps`) signature supported.
`register()`	`register()`	Identical.
`waitLocale()`	`waitLocale()`	Identical.
`getLocaleFromNavigator()`	`getLocaleFromNavigator()`	Identical.
`getLocaleFromHostname()`	`getLocaleFromHostname()`	Identical.
`getLocaleFromPathname()`	`getLocaleFromPathname()`	Identical.
`getLocaleFromQueryString()`	`getLocaleFromQueryString()`	Identical.
`getLocaleFromHash()`	`getLocaleFromHash()`	Identical.

Key differences

Message format: svelte-i18n uses its own {variable} interpolation syntax (with optional ICU-style pluralization via intl-messageformat). Sveltia I18n uses Unicode MessageFormat 2 (MF2) syntax exclusively, which is not backwards-compatible. Locale files need to be migrated.
Reactivity model: svelte-i18n exposes Svelte stores. Sveltia I18n uses Svelte 5 Runes ($state). Wrap in a reactive context (e.g. $derived) or call directly in templates — no $-prefix auto-subscription needed.

Examples

We developed Sveltia I18n to address our needs for internationalization in Svelte applications. It’s currently being used in the following production projects:

Sveltia CMS — migration commit
Sveltia UI — also powers Sveltia CMS — migration commit

Top categories

tailwind daisyui admin template popup mdsvex portfolio blog form ecommerce ui carousel auth dark seo image routing

Sveltia I18n

Sveltia I18n

Table of Contents

Installation

Usage

SvelteKit usage

Async loading with SSR

Server-side locale via Accept-Language

Client-side locale detection

API

State

locales

dictionary

isLoading()

isRTL()

Locale

locale

getLocaleFromNavigator()

getLocaleFromHostname(pattern)

getLocaleFromPathname(pattern)

getLocaleFromQueryString(key)

getLocaleFromHash(key)

Configuration

init(options)

Loader

register(localeCode, loader)

waitLocale(localeCode?)

Messages

addMessages(localeCode, ...maps)

Formatting

format(key, options?) / _(key, options?) / t(key, options?)

json(prefix, options?)

Date, time & number

date(value, options?)

time(value, options?)

number(value, options?)

Message Format

Simple interpolation

Pluralization

Ordinal numbers

Gender selection

Number formatting

Date and time

Built-in MF2 functions

Compatibility with svelte-i18n

Functions

Key differences

Examples

Top categories

Server-side locale via `Accept-Language`

`locales`

`dictionary`

`isLoading()`

`isRTL()`

`locale`

`getLocaleFromNavigator()`

`getLocaleFromHostname(pattern)`

`getLocaleFromPathname(pattern)`

`getLocaleFromQueryString(key)`

`getLocaleFromHash(key)`

`init(options)`

`register(localeCode, loader)`

`waitLocale(localeCode?)`

`addMessages(localeCode, ...maps)`

`format(key, options?)` / `_(key, options?)` / `t(key, options?)`

`json(prefix, options?)`

`date(value, options?)`

`time(value, options?)`

`number(value, options?)`