API reference
Package exports first, then what createDialect returns, then its options. Full explanations live on the other pages; this is the lookup table.
Package exports #
| Export | Signature | Description |
|---|---|---|
| createDialect svelte-dialect | (options: DialectOptions) => Dialect | Builds a dialect from the options below and returns the functions listed under “Returned by createDialect”. This is the entry for apps without SvelteKit. |
| createDialect svelte-dialect/kit | (options: DialectOptions) => Dialect | The same function for SvelteKit apps. It also fills in base from paths.base and resyncs the locale after client-side navigation. Everything exported from svelte-dialect is re-exported here. |
| Rich svelte-dialect | <Rich parts={RichPart[]} {...snippets} /> | Renders formatParts output. MF2 markup such as {#link}…{/link} goes to the snippet of the same name; markup without a snippet still renders its contents. |
| localizedEntries svelte-dialect/entries | (paths: string[], { locales, defaultLocale }) => ('*' | `/${string}`)[] | Multiplies prerender entries across locales, base-free: SvelteKit prepends paths.base itself. This standalone version can be imported in vite.config.ts, which cannot load the dialect. createDialect returns a twin that takes only the paths and uses its own locales; it is the identity when routing is off. |
Returned by createDialect #
| Export | Signature | Description |
|---|---|---|
| t | (key, params?) => string | Formats namespace:dot.path against the current locale (MF2). Params become required for keys typed via MessageParams. |
| loadTranslations | (ns: string | string[], opts?) => Promise<{ t }> | Caches namespaces for the current locale via loader, then resolves. reload refetches and replaces. |
| getLocale | () => string | Returns the current locale. |
| setLocale | (locale, opts?) => void | Switches locale, updates <html lang>/dir and the cookie; under routing navigates to the new prefix unless reload: false. |
| configure | ({ defaultLocale?, locales? }) => void | Replaces the locale set and/or the default locale after init. Invalid input warns and changes nothing. |
| locales | string[] | The selectable locales, taken from the message glob unless given. A live view: configure rewrites it in place. |
| handle | Handle | SvelteKit hooks.server.ts handle: negotiates the locale, isolates the request, fills en/ltr and sets Vary. |
| reroute | Reroute | SvelteKit hooks.ts reroute: strips the locale prefix so routes match. Only meaningful with routing: true. |
| localizeHref | (path, locale?) => string | The address of a path in a locale, the current one by default. Identity when routing is off. |
| formatParts | (key, params?) => RichPart[] | The message as render-ready parts; MF2 markup arrives as open/close/standalone. Feed it to the Rich component. |
| formatNumber | (value, options?) => string | Intl.NumberFormat for the active locale, memoised. |
| formatDate | (value, options?) => string | Intl.DateTimeFormat for the active locale, memoised. |
| getTextDirection | (locale?) => 'ltr' | 'rtl' | Writing direction for a locale, from Intl. Current locale by default. |
| localizedEntries | (paths: string[]) => ('*' | `/${string}`)[] | Multiplies prerender entries across locales, base-free: SvelteKit prepends paths.base itself. This standalone version can be imported in vite.config.ts, which cannot load the dialect. createDialect returns a twin that takes only the paths and uses its own locales; it is the identity when routing is off. |
createDialect options #
| Option | Default | Description |
|---|---|---|
| messages | {} | An import.meta.glob result. Eager entries are inlined; non-eager ones become per-namespace chunks. May be omitted when everything comes from loader. |
| defaultLocale | — | The locale served on the bare path and used as the ultimate fallback. |
| locales | from messages | Selectable locales. Defaults to those found in messages — set it explicitly when loading everything dynamically. |
| cookie | 'dialect' | A name, or { name?, maxAge?, domain?, secure? }. |
| loader | — | Fetches a namespace on demand — a database call, a fetch, a remote function. |
| routing | false | Puts the locale in the URL as a path prefix. |
| base | '' | The app's base path when served from a subdirectory. svelte-dialect/kit fills it in from paths.base; set it yourself only outside SvelteKit. |
| currentUrl | — | A reactive read of the current page URL, which resyncs the locale after client-side navigation. svelte-dialect/kit fills it in with page.url; leave it unset outside SvelteKit. |
| detectOnBarePath | false | Redirects an unprefixed document visit to the visitor's own locale. |
| strategy | ['url', 'cookie', 'lang', 'header', 'navigator', 'default'] | Lookup order for the locale, first match wins. |
| bidiIsolation | false | Wraps interpolated values in Unicode bidi isolates, for RTL locales. |
| functions | {} | Extra MF2 functions on top of the built-in set. Same name replaces one. |
| onError | console.warn | Receives every message error instead of the console. |