SvelteKit i18n

https://github.com/sveltekit-i18n/lib
Admin
SvelteKit I18n is a lightweight, dependency-free library for SvelteKit that simplifies...
Tokens:190,154
Snippets:1,228
Trust Score:5.2
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install and run an example with npm

Source: https://github.com/sveltekit-i18n/lib/blob/master/examples/README.md

Copy an example directory out of the repository, then install dependencies and start the dev server with the --open flag. Inside the repository, examples resolve sveltekit-i18n through the workspace; standalone copies resolve the published package.

```bash
npm install          # or pnpm install, yarn, …
npm run dev -- --open
```

--------------------------------

### Run the stores example with npm

Source: https://github.com/sveltekit-i18n/lib/blob/master/examples/stores/README.md

Install dependencies and start the dev server with the browser opening automatically. Run these commands in the example project root.

```bash
npm install
npm run dev -- --open

```

--------------------------------

### Run the component-scoped CSR example

Source: https://github.com/sveltekit-i18n/lib/blob/master/examples/component-scoped-csr/README.md

Install dependencies and start the development server with the browser opening automatically.

```bash
npm install
npm run dev -- --open
```

--------------------------------

### Install extension-stores

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Installs the official extension to restore the `$` store form.

```bash
npm install @sveltekit-i18n/extension-stores
```

--------------------------------

### Manual installation with npm, bun, or deno

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

Install sveltekit-i18n manually. The package is ESM-only and works on Node 22+, Bun 1.2+, or Deno 2+. Do not install @sveltekit-i18n/base or @sveltekit-i18n/parser-curly separately to avoid duplicate core instances.

```bash
npm install sveltekit-i18n
# bun add sveltekit-i18n
# deno add npm:sveltekit-i18n
```

--------------------------------

### Clone and install dependencies

Source: https://github.com/sveltekit-i18n/lib/blob/master/CONTRIBUTING.md

Clone the repository and install dependencies with pnpm. Requires Node.js 22+ and pnpm 10. The repository is ESM-only.

```bash
# Clone the repository
git clone https://github.com/sveltekit-i18n/lib.git
cd lib

# Install dependencies (also installs the git hooks via `prepare`)
pnpm install
```

--------------------------------

### Install with Svelte CLI add-on

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

Run this command in a SvelteKit 3 project to set up sveltekit-i18n via the official add-on. It prompts for locales, message format, routing, extensions, typed keys, and a demo page, then installs packages and writes configuration files.

```bash
npx sv add @sveltekit-i18n
```

--------------------------------

### common.json example

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

Example of a common namespace JSON file with frequently used translations. Keep it small – only essentials that appear across multiple pages.

```jsonc
// common.json
{
  "app.name": "My App",
  "nav.home": "Home",
  "nav.about": "About",
  "button.save": "Save",
  "button.cancel": "Cancel",
  "error.required": "This field is required"
}
```

--------------------------------

### Configure extension-stores

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Shows how to set up the extension-stores in the i18n config to get store-shaped output.

```javascript
// src/lib/i18n.js
import { I18n } from 'sveltekit-i18n';
import stores from '@sveltekit-i18n/extension-stores';

export const config = {/* ... */};

export const { t, l, locale, loading } = new I18n({ ...config, extensions: [stores] });
```

--------------------------------

### Install sveltekit-i18n

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/ARCHITECTURE.md

Install the sveltekit-i18n package. Installing @sveltekit-i18n/base or @sveltekit-i18n/parser-curly alongside it is unnecessary and harmful, as it leads to duplicate copies of the core and reactive graphs.

```bash
npm install sveltekit-i18n
```

--------------------------------

### Preprocessing with preprocess: 'none'

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Config with preprocess: 'none' and usage examples. Only top-level keys resolve; nested keys are not flattened.

```javascript
const config = {
  preprocess: 'none',
};
```

```svelte
<!-- ❌ nothing flattened this key -->
<h1>{i18n.t('home.title')}</h1>

<!-- ❌ resolves, but the message is a whole namespace: the parser renders it as JSON text -->
<h1>{i18n.t('home')}</h1>

<!-- ✅ read the table directly when you keep the nested structure -->
<h1>{i18n.translations[i18n.locale]?.home?.title}</h1>
```

--------------------------------

### Install @sveltekit-i18n/typegen

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

Install the typegen Vite plugin as a dev dependency to generate the schema from your translations during vite build and dev.

```bash
npm install -D @sveltekit-i18n/typegen
```

--------------------------------

### Example test structure for parser wiring

Source: https://github.com/sveltekit-i18n/lib/blob/master/CONTRIBUTING.md

Shows the typical structure of a Vitest spec in this package: imports from 'vitest' and the public API, an inline translation config (no loader needed), and an assertion on the interpolated result. The test setup requires `@sveltejs/vite-plugin-svelte` and the core inlined in `vitest.config.ts`.

```typescript
import { describe, expect, it } from 'vitest';
import { I18n } from '../../src';

describe('parser wiring', () => {
  it('interpolates without the consumer supplying a parser', () => {
    // Arrange - inline translations need no loader, so nothing is awaited
    const i18n = new I18n({
      initLocale: 'en',
      translations: { en: { greeting: 'Hello, {{name}}!' } },
    });

    // Act - execute the code
    const greeting = i18n.t('greeting', { name: 'Jarda' });

    // Assert - verify the result
    expect(greeting).toBe('Hello, Jarda!');
  });
});
```

--------------------------------

### matchLocale usage example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/utils.md

Example of using matchLocale with an Accept-Language header and a list of available locales. Shows matching with q-weights and prefix truncation, returning undefined for a miss.

```javascript
import { matchLocale } from 'sveltekit-i18n/utils';

matchLocale('en-GB,en;q=0.9,cs;q=0.8', ['en', 'cs']); // 'en'
matchLocale('cs-CZ', ['en', 'cs']);                   // 'cs'
matchLocale('de-AT', ['en', 'cs']);                   // undefined
```

--------------------------------

### Run the development server

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/GETTING_STARTED.md

Start the SvelteKit dev server with `npm run dev`. Visit `http://localhost:5173` and view the page source to see translated text and `<html lang>` already in the server-sent HTML.

```bash
npm run dev
```

--------------------------------

### setRoute(route, options?) Usage Example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n-methods.md

Shows how to set the route from a SvelteKit load function.

```javascript
// server-side load for the root layout
export const load = async ({ url }) => {
  await i18n.setRoute(url.pathname);
};
```

--------------------------------

### Benchmark with git worktree and compare

Source: https://github.com/sveltekit-i18n/lib/blob/master/CONTRIBUTING.md

Measures the package's performance against a checked-out version. Requires a git worktree and installing dependencies in the comparison directory.

```bash
git worktree add ../master origin/master
cd ../master && pnpm install --frozen-lockfile --ignore-scripts && cd -
pnpm run bench --compare ../master
```

--------------------------------

### Apply extensions with config.extensions

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

Pipe the constructed instance through adapter functions left to right; new I18n(config) evaluates to the last one's output. This example adds the store surface via extension-stores.

```javascript
import { I18n } from 'sveltekit-i18n';
import stores from '@sveltekit-i18n/extension-stores';

export const { t, locale, loading } = new I18n({ ...config, extensions: [stores] });
```

--------------------------------

### Good Commit Examples

Source: https://github.com/sveltekit-i18n/lib/blob/master/CONTRIBUTING.md

Examples of well-formed commit messages that follow the conventional format and are self-contained and meaningful.

```plaintext
feat: compose the runes core with parser-curly
fix(config): keep the parser through a reconfiguration
docs: document the extensions pipe
test: cover the re-export surface
chore(deps): bump vitest to 4
```

--------------------------------

### Descriptive names (bad vs good)

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

Use descriptive, hierarchical key names instead of generic ones. The bad example uses `t1`, `btn`, `txt`; the good example uses `home.welcome.title`, `common.button.submit`, `greeting.message`.

```jsonc
// ❌ Bad
{ "t1": "Welcome", "btn": "Click", "txt": "Hello" }

// ✅ Good
{
  "home.welcome.title": "Welcome",
  "common.button.submit": "Submit",
  "greeting.message": "Hello"
}
```

--------------------------------

### Solution: +layout.js load starts a load

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Correct load function that calls i18n.loadTranslations with locale and pathname, ensuring translations load.

```javascript
// ✅ +layout.js
import { i18n } from '#lib/i18n.js';

export const load = async ({ url }) => {
  await i18n.loadTranslations('en', url.pathname);

  return {};
};
```

--------------------------------

### ESM import examples for sveltekit-i18n

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Shows correct and incorrect ways to import the ESM-only package. Use the import statement or dynamic import from CommonJS; require() fails with ERR_REQUIRE_ESM.

```javascript
// ❌
const { I18n } = require('sveltekit-i18n');
```

```javascript
// ✅
import { I18n } from 'sveltekit-i18n';
```

```javascript
// ✅ from a CommonJS file, if you must
const { I18n } = await import('sveltekit-i18n');
```

--------------------------------

### Bad Commit Examples

Source: https://github.com/sveltekit-i18n/lib/blob/master/CONTRIBUTING.md

Examples of commit messages that should be avoided because they are not descriptive or meaningful.

```plaintext
WIP
fixes
Update stuff
Changed some files
lots of changes
```

--------------------------------

### Mock module's get to provide real I18n instance in component test

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/GETTING_STARTED.md

A component that reads the instance through get() finds it where use() put it, which a test renders without. Hand it a real instance by mocking your module's get.

```javascript
import { render } from '@testing-library/svelte';
import { vi } from 'vitest';
import Greeting from '#lib/components/Greeting.svelte';

vi.mock('#lib/i18n.js', async () => {
  const { I18n } = await import('sveltekit-i18n');
  const i18n = new I18n({
    initLocale: 'en',
    translations: { en: { 'common.greeting': 'Hello, {{name}}!' } },
  });

  return { get: () => i18n };
});

render(Greeting);
```

--------------------------------

### Use get() in any component

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/kit.md

In any component below the root layout, call `get()` to retrieve the instance and use it for translations. Throws if no instance is found.

```svelte
<!-- any component -->
<script>
  import { get } from '#lib/i18n.js';

  const i18n = get();
</script>

<p>{i18n.t('common.greeting', { name: 'World' })}</p>
```

--------------------------------

### Problem: +layout.js load does not start a load

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Shows the incorrect load function that does not request a locale or route, causing translations not to load.

```javascript
// ❌ +layout.js
export const load = async ({ url }) => {
  // Nothing requests a locale or a route
  return {};
};
```

--------------------------------

### Wrong translation key example

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Shows a missing key 'home.titel' and the correct JSON with 'home.title'. The key must match exactly.

```svelte
<!-- ❌ Key doesn't exist -->
<h1>{i18n.t('home.titel')}</h1>
```

```json
{
  "home.title": "Welcome"
}
```

--------------------------------

### loadConfig(config) Usage Example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n-methods.md

Shows how to call loadConfig with a configuration object. The first call sets up the i18n instance; the second call demonstrates error handling when a loader fails.

```javascript
const i18n = new I18n();

await i18n.loadConfig({
  initLocale: 'en',
  fallbackLocale: 'en',
  loaders: [{ locale: ['en', 'cs'], namespace: 'common', loader: async () => ({}) }],
});

try {
  await i18n.loadConfig({ loaders: [badDescriptor] }); // e.g. a loader that throws synchronously
} catch (error) {
  // 'Failed to load the i18n config.' was logged; error is the thrown value
}
```

--------------------------------

### log configuration example

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/README.md

Configures the core's diagnostic logging with level, prefix, and logger. Every level method takes the prefixed message; a thrown value follows as a second argument. A custom logger may omit levels it does not care about.

```javascript
const config = {
  log: {
    level: 'warn',            // 'error' | 'warn' | 'debug'
    prefix: '[MyApp i18n]: ',
    logger: console,          // anything matching `Logger.T`
  },
};
```

--------------------------------

### Define i18n config with schema registration

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/GETTING_STARTED.md

Example config module that exports the config and the i18n instance, with a comment indicating the config is as in Step 2.

```javascript
// src/lib/i18n.js
// @ts-check
import { defineI18n } from 'sveltekit-i18n/kit';

export const config = {/* as in Step 2 */};

export const { handle, load, use, get } = defineI18n(config, {
  preferredLocale: (event) => event.cookies?.get('lang'),
});
```

--------------------------------

### Curly message format example with placeholders, modifiers, and options

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/README.md

Shows the Curly Message Format syntax for placeholders with modifiers, options, and defaults. Placeholders name a payload key and may carry a modifier, options, and a default. The example includes greeting, welcome, price, updated, items, and stock messages.

```json
{
  "greeting": "Hello, {{name}}!",
  "welcome": "Welcome, {{name; default:Guest;}}!",
  "price": "Total: {{amount:number;}}",
  "updated": "Updated {{time:ago;}}",
  "items": "You have {{count}} {{count:plural; one:item; other:items;}}.",
  "stock": "{{count:gt; 0:In stock ({{count}}); default:Out of stock;}}"
}
```

--------------------------------

### i18n.t() usage examples with Curly message placeholders

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/README.md

Demonstrates calling i18n.t() with payload keys to render messages. Each call passes a payload object; the output shows how placeholders, modifiers, options, and defaults resolve. For example, 'welcome' uses the default 'Guest' when no name is provided, and 'price' formats the number with the 'number' modifier.

```javascript
i18n.t('greeting', { name: 'Alice' })        // → "Hello, Alice!"
i18n.t('welcome', {})                        // → "Welcome, Guest!"
i18n.t('price', { amount: 1234.56 })         // → "Total: 1,234.56"
i18n.t('updated', { time: -3600000 })        // → "Updated 1 hour ago"
i18n.t('items', { count: 1 })                // → "You have 1 item."
i18n.t('stock', { count: 0 })                // → "Out of stock"
```

--------------------------------

### loaders descriptor example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/configuration.md

Defines loaders for every page and for product routes. The first loader imports JSON per locale and namespace; the second fetches product data for routes matching /^\/products/, passing named route params to the loader.

```javascript
const config = {
  loaders: [
    // Every page, one call per locale and namespace
    {
      locale: ['en', 'cs'],
      namespace: ['common', 'nav'],
      loader: async ({ locale, namespace }) => (await import(`./${locale}/${namespace}.json`)).default,
    },
    // Product pages only; a named group is a route param, handed to the loader
    {
      locale: 'en',
      namespace: 'products',
      routes: [/^\/products/],
      loader: async ({ locale, params }) => (await fetch(`${ORIGIN}/api/${locale}/products`)).json(),
    },
  ],
};
```

--------------------------------

### log configuration example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/configuration.md

Configures the core's diagnostics logger with level 'warn', a custom prefix, and a custom logger object. The parser's diagnostics are separate and silent by default.

```javascript
const config = {
  log: {
    level: 'warn',            // 'error' | 'warn' | 'debug'
    prefix: '[MyApp i18n]: ',
    logger: console,          // anything matching Logger.T
  },
};
```

--------------------------------

### Define i18n config and wire it (src/lib/i18n.js)

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

Configures locales, namespaces, and loaders for sveltekit-i18n/kit. Exports handle, load, use, and get functions. The loader is called once per locale-namespace pair.

```javascript
// src/lib/i18n.js
import { defineI18n } from 'sveltekit-i18n/kit';

/** @satisfies {import('sveltekit-i18n').Config} */
export const config = {
  initLocale: 'en',
  loaders: [
    {
      locale: ['en', 'cs'],
      namespace: 'common',
      loader: async ({ locale, namespace }) => (await import(`./translations/${locale}/${namespace}.json`)).default,
    },
  ],
};

export const { handle, load, use, get } = defineI18n(config, {
  preferredLocale: (event) => event.cookies?.get('lang'),
});
```

--------------------------------

### setLocale(locale?) Usage Example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n-methods.md

Shows how to switch locales and set a cookie after the locale loads.

```javascript
const switcher = async (locale) => {
  await i18n.setLocale(locale);   // page text flips when the load resolves
  document.cookie = `lang=${locale}; path=/; max-age=31536000; samesite=lax`;
};
```

--------------------------------

### Build error when routes are not prerendered

Source: https://github.com/sveltekit-i18n/lib/blob/master/examples/locale-router/README.md

Shown as the failure message when the crawler cannot discover all locale routes without entries.

```text
The following routes were marked as prerenderable, but were not prerendered
because they were not found while crawling your app
```

--------------------------------

### preload Usage Example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n-methods.md

Prefetches translations for a hovered link's target route. The returned token can be passed to loadTranslations later to show the fetched data without re-fetching.

```javascript
const token = await i18n.preload('cs', '/cs/about'); // a hovered link's target
// later, at commit: await i18n.loadTranslations('cs', '/cs/about', { preloaded: token });
```

--------------------------------

### get()

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/kit.md

Returns the current i18n instance. The instance is the piped surface, so it includes extensions from the config.

```APIDOC
## get()

### Description
Returns the current i18n instance. The instance is the piped surface, so it includes extensions from the config.

### Returns
`Instance` - The i18n instance.
```

--------------------------------

### v3 await load methods (solution)

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Shows the v3 way to await the load-starting methods directly.

```javascript
// ✅ await what started the load
await i18n.loadTranslations('cs', '/about');
await i18n.setLocale('cs');
await i18n.setRoute('/about');
await i18n.loadConfig(config);
```

--------------------------------

### Svelte script block for mdsvex page

Source: https://github.com/sveltekit-i18n/lib/blob/master/examples/mdsvex/src/routes/[lang=locale]/guide/+page.svx

This script block runs in a .svx file, which mdsvex converts into a Svelte component. It imports NAMESPACES and get from the translations module, initializes i18n, and computes the loaded namespaces using $derived.

```svelte
<script>
  import { NAMESPACES, get } from '#lib/translations/index.js';

  // Exactly what a .svelte page would do — by the time this runs, mdsvex has
  // already turned the file into an ordinary Svelte component.
  const i18n = get();

  // The shell strings sit in `config.translations` under their own flat keys;
  // only the configured namespaces were actually loaded.
  const loaded = $derived(NAMESPACES
    .map(({ namespace }) => namespace)
    .filter((namespace) => Object.hasOwn(i18n.rawTranslations[i18n.locale] ?? {}, namespace))
    .join(', '));
</script>
```

--------------------------------

### loadTranslations Usage Examples

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n-methods.md

Three usage patterns: activating load for a page, warm fill without activation, and navigation with a preload token. Each call returns a Promise that resolves when the operation completes.

```javascript
// client-only app: load for a page and activate
await i18n.loadTranslations('en', '/about');

// warm fill: fetch for a future navigation without changing what is shown
await i18n.loadTranslations('cs', '/about', { activate: false });

// navigation: show what a preload fetched, without fetching it again
const token = await i18n.preload('cs', '/about');
await i18n.loadTranslations('cs', '/about', { preloaded: token });
```

--------------------------------

### Markdown content with Svelte expressions

Source: https://github.com/sveltekit-i18n/lib/blob/master/examples/mdsvex/src/routes/[lang=locale]/guide/+page.svx

The rest of the .svx file uses Svelte expressions to render translated strings. It includes a badge, heading, intro, and step headings with dynamic numbers, followed by code blocks for installation, configuration, and rendering.

```markdown
<span class="badge">{i18n.t('guide.badge')}</span>

# {i18n.t('guide.heading')}

{i18n.t('guide.intro')}

## {i18n.t('guide.step', { n: 1 })} — {i18n.t('guide.install')}

```bash
npm install sveltekit-i18n
```

## {i18n.t('guide.step', { n: 2 })} — {i18n.t('guide.configure')}

```javascript
export const config = {
  translations: { en: { hello: 'Hello' } },
};
```

## {i18n.t('guide.step', { n: 3 })} — {i18n.t('guide.render')}

```svelte
<h1>{i18n.t('hello')}</h1>
```

<p class="note"><strong>{i18n.t('guide.loaded')}:</strong> <code>{loaded}</code></p>
```

--------------------------------

### Using resolveLoaders in JavaScript

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/utils.md

Example of calling resolveLoaders with config.loaders and config.sanitizeLocales. The output shows an array of resolved loader objects with locale, namespace, loader, routes, and id.

```javascript
import { resolveLoaders } from 'sveltekit-i18n/utils';

resolveLoaders(config.loaders, config.sanitizeLocales);
// [{ locale: 'en', namespace: 'common', loader, routes, id: '["en","common"]' }, ...]
```

--------------------------------

### Define i18n with sveltekit-i18n/kit

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Use this setup to replace the removed getTranslationProps() function. It creates the handle, load, use, and get functions from the kit module.

```javascript
// src/lib/i18n.js
import { defineI18n } from 'sveltekit-i18n/kit';

export const config = {/* ... */};

export const { handle, load, use, get } = defineI18n(config);
```

--------------------------------

### No dots in namespaces - invalid and valid examples

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Namespace keys cannot contain dots. Using a dot (e.g., 'pages.home') is reported at config time and won't work correctly. Use underscores or a flat name instead.

```javascript
// ❌ Won't work correctly (and is reported at config time)
{ namespace: 'pages.home' }

// ✅
{ namespace: 'pages_home' }
{ namespace: 'home' }
```

--------------------------------

### get()

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/kit.md

A function that returns the i18n instance provided by `use()` in any component below the root layout, including error pages. It throws if no instance is found.

```APIDOC
## `get()`

### Description
A function that returns the i18n instance provided by `use()` in any component below the root layout, including error pages. It throws if no instance is found.

### Signature
```ts
get: () => Instance;
```

### Usage
```svelte
<!-- any component -->
<script>
  import { get } from '#lib/i18n.js';

  const i18n = get();
</script>

<p>{i18n.t('common.greeting', { name: 'World' })}</p>
```

### Errors
Anywhere else it **throws**: `Error: '[i18n]: \`get()\` found no instance. Call \`use(() => data)\` in the root \`+layout.svelte\`.'` (`@sveltekit-i18n/base/dist/kit/define.svelte.js:285`).
```

--------------------------------

### Using toDotNotation in a preprocess function

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/utils.md

Example of using `toDotNotation` in a custom `preprocess` function to flatten translation data while merging defaults. The `preprocess` function replaces the built-in flattening, so call this to still get dot notation.

```javascript
import { toDotNotation } from 'sveltekit-i18n/utils';

const defaults = { common: { error: 'An error occurred' } };

const config = {
  preprocess: (input) => toDotNotation({ ...defaults, ...input }),
};

// i18n.t('common.error')
```

--------------------------------

### Use a custom parser with @sveltekit-i18n/base

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

Build directly on @sveltekit-i18n/base to use a different message parser, such as parser-icu. This is the only case where installing the core directly is appropriate; you are not using this package then.

```javascript
import { I18n } from '@sveltekit-i18n/base';
import parser from '@sveltekit-i18n/parser-icu';

const config = {
  parser: parser({ onReport: null }),
  // ... rest of config
};
```

--------------------------------

### Define i18n config and export handle, load, use, get

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/kit.md

Full example of setting up sveltekit-i18n in a SvelteKit project. Defines the config with initLocale, fallbackLocale, translations, and loaders, then calls defineI18n with a preferredLocale function that reads the 'lang' cookie.

```javascript
// src/lib/i18n.js
import type { Config } from 'sveltekit-i18n';
import { defineI18n } from 'sveltekit-i18n/kit';

export const config = {
  initLocale: 'en',
  fallbackLocale: 'en',
  translations: { /* shell strings, present before any loader runs */ },
  loaders: [
    {
      locale: ['en', 'cs'],
      namespace: 'home',
      routes: ['/'],
      loader: async ({ locale, namespace }) => (await import(`./translations/${locale}/${namespace}.json`)).default,
    },
  ],
} satisfies Config;

export const { handle, load, use, get } = defineI18n(config, {
  preferredLocale: (event) => event.cookies?.get('lang'),
});
```

--------------------------------

### Per-request instance wiring with defineI18n

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

Exports the config as inert data and uses defineI18n from 'sveltekit-i18n/kit' to build functions that create a fresh instance per request. Components reach the instance through get() (Svelte context) rather than importing the instance directly.

```javascript
// ✅ src/lib/i18n.js — the config is inert data, the wiring builds instances
import { defineI18n } from 'sveltekit-i18n/kit';

export const config = {
  initLocale: 'en',
  loaders: [/* … */],
};

export const { handle, load, use, get } = defineI18n(config);
```

--------------------------------

### v3 instance usage (solution)

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Shows the v3 pattern using `i18n.t` and `i18n.locale` from the reactive instance.

```svelte
<!-- ✅ v3 -->
<script>
  import { i18n } from '#lib/i18n.js';
</script>

<h1>{i18n.t('home.title')}</h1>
<p>{i18n.locale}</p>
```

--------------------------------

### Create a real I18n instance with translations

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/GETTING_STARTED.md

A real instance is cheap and synchronous; translations are available before any loader runs, so a test needs no loader, no await, and no mock.

```javascript
import { I18n } from 'sveltekit-i18n';

const i18n = new I18n({
  initLocale: 'en',
  translations: { en: { 'common.greeting': 'Hello, {{name}}!' } },
});

i18n.t('common.greeting', { name: 'Alice' }); // → "Hello, Alice!"
```

--------------------------------

### Preprocessing input payload with nested user object

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/ARCHITECTURE.md

Example input payload before preprocessing. The default 'full' preprocess flattens nested objects and arrays to dot notation.

```json
{
  "user": {
    "profile": { "name": "Name", "email": "Email" }
  }
}
```

--------------------------------

### Use extension-stores to get store surface

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

Adds the store form of the instance ($t, locale, loading) via the extension-stores package. Destructuring at module level reintroduces shared instance issues; put the extension in the config handed to defineI18n() instead.

```javascript
import { I18n } from 'sveltekit-i18n';
import stores from '@sveltekit-i18n/extension-stores';

const { t, locale, loading, instance } = new I18n({ ...config, extensions: [stores] });
```

--------------------------------

### get() function signature

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/kit.md

Type signature for `get()`. It returns the instance provided by `use()`.

```typescript
get: () => Instance;
```

--------------------------------

### snapshot() and hydrate() Usage Example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n-methods.md

Server branch of a layout load captures an envelope with snapshot({ records: true }); the client receives it and restores the state with hydrate(envelope). A plain hand-off uses hydrate({ translations }).

```javascript
// server branch of a layout load
const envelope = i18n.snapshot({ records: true });
return { i18n: envelope };

// client receives it and restores the state
i18n.hydrate(envelope); // or, a plain hand-off: i18n.hydrate({ translations })
```

--------------------------------

### Run test suite commands

Source: https://github.com/sveltekit-i18n/lib/blob/master/CONTRIBUTING.md

Commands to build, typecheck, run the full suite, narrow to matching spec files, watch mode, and typecheck. `pnpm test` runs `pretest` first, which builds and typechecks; a bare `vitest` run skips that step, so build once before using watch mode.

```bash
# Build, typecheck, then run the whole suite
pnpm test

# Narrow the run to matching spec files
pnpm test exports

# Watch mode (build `dist/` first - see below)
pnpm exec vitest

# Typecheck `src`, `tests` and `bench` - how `types.spec.ts` makes its assertions
pnpm run typecheck
```

--------------------------------

### l function usage example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n.md

JavaScript example of calling `l` with an explicit locale and payload.

```javascript
const inCzech = i18n.l('cs', 'common.greeting', { name: 'Ada' }); // "Ahoj, Ada!"
```

--------------------------------

### Hook into SvelteKit: app.html placeholders

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

Uses %lang% and %dir% placeholders in app.html, which are filled by the handle function.

```html
<!-- src/app.html -->
<html lang="%lang%" dir="%dir%">
```

--------------------------------

### Git workflow: create branch, commit, rebase, push

Source: https://github.com/sveltekit-i18n/lib/blob/master/CONTRIBUTING.md

Standard rebase-based workflow: create a feature branch, commit atomically, rebase on master, and push with --force-with-lease.

```bash
# Create a feature branch (use any descriptive name)
git checkout -b my-descriptive-branch-name

# Make changes and commit atomically
git add .
git commit -m "fix: correct the loader match"

# Keep your branch updated (rebase, NOT merge)
git fetch origin
git rebase origin/master

# Push (use force-with-lease after rebase)
git push origin my-descriptive-branch-name --force-with-lease
```

--------------------------------

### sanitizeLocales usage example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/utils.md

Example of using sanitizeLocales to normalize a locale from a page parameter and set it if it differs from the current locale.

```javascript
import { sanitizeLocales } from 'sveltekit-i18n/utils';

const [locale] = sanitizeLocales(page.params.lang); // 'en-us' -> 'en-US'

if (locale && locale !== i18n.locale) await i18n.setLocale(locale);
```

--------------------------------

### Mock #lib/i18n.js get to return a real I18n instance

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/README.md

Mocks the module's get function to return a real I18n instance configured with inline translations. This lets a component that reads the instance via get() from #lib/i18n.js find it where use() put it, without rendering the actual module.

```javascript
vi.mock('#lib/i18n.js', async () => {
  const { I18n } = await import('sveltekit-i18n');
  const i18n = new I18n({ initLocale: 'en', translations: { en: { 'common.greeting': 'Hello, {{name}}!' } } });

  return { get: () => i18n };
});
```

--------------------------------

### Write a custom extension with withGreeting

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/README.md

Shows a minimal custom extension that adds a greet method to the instance. The extension receives the i18n instance and returns it with the new method, then the method is called directly.

```javascript
const withGreeting = (i18n) => Object.assign(i18n, {
  greet: (name) => i18n.t('common.greeting', { name }),
});

export const i18n = new I18n({ ...config, extensions: [withGreeting] });

i18n.greet('World');
```

--------------------------------

### v2 await loading.toPromise (problem)

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Shows the v2 pattern of awaiting `loading.toPromise()`, which is not available in v3.

```javascript
// ❌ v2
await loading.toPromise();
```

--------------------------------

### Example translation object

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/GETTING_STARTED.md

Translations are nested objects flattened to dot notation. This example is read as i18n.t('common.nav.home') — the loader's namespace, then the path inside the file.

```json
{ "nav": { "home": "Home" } }
```

--------------------------------

### t function usage examples

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n.md

JavaScript examples of calling `t` with a payload and props. Shows that a missing key returns the key itself or `config.fallbackValue`.

```javascript
const greeting = i18n.t('common.greeting', { name: 'World' });
const price = i18n.t('product.price', { value: 99.9 }, { number: { maximumFractionDigits: 2 } });
// missing key → 'common.nonexistent' (or config.fallbackValue)
```

--------------------------------

### File size guidelines directory structure

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

Target sizes: common.json < 5 KB, page-specific < 20 KB per file. If larger, split into sub-namespaces or route-scoped loaders.

```text
products/
├── list.json      # product listing page
├── detail.json    # product detail page
├── compare.json   # product comparison
└── reviews.json   # product reviews
```

--------------------------------

### Basic configuration with I18n instance

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/README.md

Defines the core configuration object and creates an I18n instance. All slots are optional; an instance with no config is valid and renders nothing until loadConfig() is called.

```javascript
import { I18n } from 'sveltekit-i18n';

/** @type {import('sveltekit-i18n').Config} */
export const config = {
  loaders: [/* ... */],
  parserOptions: {/* parser-curly options */},
};

export const i18n = new I18n(config);
```

--------------------------------

### Example: check and set locale

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/i18n.md

Example usage of the `locale` property: if the current locale is not 'cs', set it to 'cs' using `setLocale`. This is a reactive read and a fire-and-forget setter.

```javascript
if (i18n.locale !== 'cs') await i18n.setLocale('cs');
```

--------------------------------

### cst() usage example

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/parser.md

Example of calling cst() with a message containing a placeholder. The output shows the resulting concrete syntax tree with node types and spans.

```javascript
import { cst } from 'sveltekit-i18n';

cst('Hello, {{name; default:Guest;}}!');
// → { type: 'message', start: 0, end: 32, nodes: [
//     { type: 'text', start: 0, end: 7 },
//     { type: 'placeholder', start: 7, end: 31, nodes: [/* ... */] },
//     { type: 'text', start: 31, end: 32 },
//   ] }
```

--------------------------------

### Kit.T return type

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/api-reference/kit.md

The object returned by defineI18n, containing handle, load, use, and get functions. Each is safe to export on its own. Instance is the piped surface, so data.i18n, use(), and get() all hand out what config.extensions makes of the instance.

```typescript
// @sveltekit-i18n/base/dist/kit/types.d.ts:79
type T<Instance = I18n> = {
  handle: (input: { event: RequestEvent<Partial<Record<string, any>>>; resolve: Resolve }) => Promise<Response>;
  load: {
    (event: ServerLoadEvent<Partial<Record<string, any>>>): Promise<{ i18n: Payload }>;
    <E extends UniversalLoadEvent<Partial<Record<string, any>>>>(event: E): Promise<Omit<NonNullable<E['data']>, 'i18n'> & { i18n: Instance }>;
    (event: UniversalLoadEvent<Partial<Record<string, any>>>): Promise<{ i18n: Instance }>;
  };
  use: (data: () => object | null | undefined) => Instance;
  get: () => Instance;
};
```

--------------------------------

### Build the instance the application renders with (src/routes/+layout.js)

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/README.md

Universal load that runs on server and client. On the server it creates a new I18n instance, hydrates from the server snapshot, and loads missing translations. In the browser it reuses the instance and handles preloads by calling preload() and returning a commit token.

```javascript
// src/routes/+layout.js
import { I18n } from 'sveltekit-i18n';
import { DEFAULT_LOCALE, config } from '#lib/i18n.js';

// Assigned in the browser only — on the server this module-level binding
// would be the shared state we are avoiding.
let client;

export const load = async ({ data, url }) => {
  // `data` is null when no route matched: the error page renders through this
  // load too, and on a static host that is every unknown URL.
  if (client) {
    // A later pass may be a preload, which shows nothing: the layout hands
    // its token to the call that commits the navigation.
    const locale = data?.i18n?.locale ?? client.locale;
    const preloaded = await client.preload(locale, url.pathname);

    return { i18n: client, commit: { locale, route: url.pathname, preloaded } };
  }

  const i18n = new I18n(config);

  i18n.hydrate(data?.i18n);

  if (!import.meta.env.SSR) client = i18n;

  await i18n.loadTranslations(data?.i18n?.locale ?? DEFAULT_LOCALE, url.pathname);

  return { i18n };
};
```

--------------------------------

### Configure loaders with routes in src/lib/i18n.js

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/GETTING_STARTED.md

Define a `fromFile` loader that dynamically imports JSON files. The `config` object sets `initLocale`, `translations`, and `loaders`. Loaders without `routes` run on every page; those with `routes` run only on matching paths. `routes` can be exact strings, regular expressions, or anything with a `test(route)` method.

```javascript
// src/lib/i18n.js
const fromFile = async ({ locale, namespace }) => (await import(`./translations/${locale}/${namespace}.json`)).default;

export const config = {
  initLocale: 'en',
  translations: {
    en: { 'lang.en': 'English', 'lang.cs': 'Czech' },
    cs: { 'lang.en': 'Angličtina', 'lang.cs': 'Čeština' },
  },
  loaders: [
    // No `routes` → loaded on every page
    { locale: ['en', 'cs'], namespace: 'common', loader: fromFile },

    // Homepage only
    { locale: ['en', 'cs'], namespace: 'home', routes: ['/'], loader: fromFile },

    // About page only
    { locale: ['en', 'cs'], namespace: 'about', routes: ['/about'], loader: fromFile },
  ],
};
```

--------------------------------

### Catching get() without use() error

Source: https://github.com/sveltekit-i18n/lib/blob/master/_autodocs/errors.md

Use try/catch to handle the Error thrown when get() is called without a prior use() call in the root layout. The catch block sets i18n to null as a fallback, rendering untranslated content.

```svelte
<script>
  import { get } from '#lib/i18n.js';

  let i18n;
  try {
    i18n = get();
  } catch {
    i18n = null; // fallback: layout wiring missing — renders untranslated
  }
</script>
```

--------------------------------

### Universal load in root layout

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/GETTING_STARTED.md

Exports load from #lib/i18n.js for client-side instance creation.

```javascript
// src/routes/+layout.js
export { load } from '#lib/i18n.js';
```

--------------------------------

### Mock i18n with a real instance in Vitest

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

Use a real I18n instance built from translations alone; it is synchronous and requires no loader. Mock the module's get to return the instance so components using get() find it. Per-test instances avoid state reset between cases.

```javascript
import { render } from '@testing-library/svelte';
import { expect, test, vi } from 'vitest';
import Greeting from '#lib/components/Greeting.svelte';

vi.mock('#lib/i18n.js', async () => {
  const { I18n } = await import('sveltekit-i18n');
  const i18n = new I18n({
    initLocale: 'en',
    translations: { en: { 'common.greeting': 'Hello, {{name}}!' } },
  });

  return { get: () => i18n };
});

// Greeting calls get() and renders i18n.t('common.greeting', { name })
test('greets the user', () => {
  const { getByText } = render(Greeting, { props: { name: 'Alice' } });

  expect(getByText('Hello, Alice!')).toBeInTheDocument();
});
```

--------------------------------

### initialized

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

A boolean that is true once a locale and a route are set and translations are present. This indicates that the instance is ready for use.

```APIDOC
## initialized

### Description
A boolean that is true once a locale and a route are set and translations are present. This indicates that the instance is ready for use.

### Type
- boolean (read-only)
```

--------------------------------

### Avoid deep nesting (better)

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

Balanced nesting is better. This example is marked as ✅ Better.

```json
{ "profile.privacy.public": "Public" }
```

--------------------------------

### Client-only i18n instance (src/lib/i18n.js)

Source: https://github.com/sveltekit-i18n/lib/blob/master/README.md

Creates an I18n instance for client-only apps without server wiring. The config is as in step 2.

```javascript
// src/lib/i18n.js
import { I18n } from 'sveltekit-i18n';

export const config = {/* as in step 2 */};

export const i18n = new I18n(config);
```

--------------------------------

### Avoid deep nesting (too deep)

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

Too deep nesting is harder to maintain. This example is marked as ❌ Too deep.

```json
{ "pages.user.profile.settings.privacy.options.visibility.public": "Public" }
```

--------------------------------

### App config with extension (src/lib/i18n.js)

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/BEST_PRACTICES.md

The app imports withTable and adds it to the extensions array in its config. The extension runs wherever an instance is handed out, ensuring strings are present on both sides without travelling in the snapshot.

```javascript
// src/lib/i18n.js
import { withTable } from 'acme-table/i18n';

export const config = { ...appConfig, extensions: [withTable] };
```

--------------------------------

### Regex with leading slash matches correctly

Source: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md

Use /^\/products/ to match routes starting with '/products'. The backslash escapes the slash in the regex pattern.

```javascript
routes: [/^\/products/]  // ✅ Note the \/ at the start
```
Tokens:
Raw