sveltekit-i18n extensions

Official extensions for the @sveltekit-i18n/base config.extensions pipe.

An extension is a plain function (input) => output. The I18n constructor pipes the freshly configured instance through every extension in config.extensions, left to right, and new I18n(config) evaluates to the last extension's output:

import I18n from '@sveltekit-i18n/base';

const i18n = new I18n({
  ...config,
  extensions: [extensionA, extensionB],
}); // = extensionB(extensionA(instance))

An extension can augment the instance (attach new capabilities) or replace it entirely with a different consumption surface. The result type is inferred end to end — TypeScript folds the instance type through the extensions tuple.

Available Extensions

@sveltekit-i18n/extension-stores

Replaces the runes-based instance with the Svelte-store surface known from sveltekit-i18n v2 ($t, $locale, $loading, ...), plus pass-through methods and an instance escape hatch.

npm i -D @sveltekit-i18n/base @sveltekit-i18n/extension-stores

import I18n from '@sveltekit-i18n/base';
import stores from '@sveltekit-i18n/extension-stores';

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

See the package README for the full output reference and v2 migration notes.

Creating Custom Extensions

You don't need this repository to write an extension — any function works:

import I18n from '@sveltekit-i18n/base';

const withGreeting = <T extends { locale: unknown }>(i18n: T) => ({
  ...i18n,
  greet: () => `Hello from ${String(i18n.locale)}!`,
});

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

Guidelines:

• Extensions run at construction time, once, after the synchronous prefix of the config load — they receive a configured instance (with synchronous translations and initLocale, the initial locale is already active).
• If your extension replaces the instance, expose the original one under an instance key so consumers keep an escape hatch to the full API.
• Memoize per instance (e.g. via a WeakMap) if your extension may be applied to the same instance more than once.

See the @sveltekit-i18n/base docs for the full extensions reference.

Documentation

• 🌐 sveltekit-i18n.github.io – The documentation site, with a live playground
• 📖 @sveltekit-i18n/base docs – The core, and the extensions reference
• 📚 Documentation Index – Guides, tutorials and best practices

Issues

This repository is a part of the sveltekit-i18n ecosystem. Please report issues here.

Sponsor

You can support the maintenance of these packages through GitHub Sponsors.