@effuse/i18n

@effuse/i18n provides nested translations, interpolation, pluralization, locale fallback, lazy locale loading, and request-scoped server rendering.

Install

pnpm add @effuse/i18n

Basic Usage

import { createI18n, defineTranslations } from '@effuse/i18n';

const en = defineTranslations({
	greeting: 'Hello, {{name}}!',
	items: { one: '{{count}} item', other: '{{count}} items' },
});

export const i18n = createI18n({
	defaultLocale: 'en',
	fallbackLocale: 'en',
	translations: { en },
	loader: async (locale) => {
		const response = await fetch(`/locales/${locale}.json`);
		if (!response.ok) throw new Error(`Unable to load ${locale}`);
		return response.json();
	},
});

import { t, setLocale } from '@effuse/i18n';

t('greeting', { name: 'Ada' });
await setLocale('es');

Locale changes are transactional. Concurrent requests for the same unloaded locale share one loader call, only the latest requested locale becomes active, and a failed load rejects with LocaleLoadError without changing or persisting the current locale.

Server Rendering

Create one instance per request and bind it while rendering. Request-scoped instances disable browser detection and persistence by default, preventing locale state from leaking between concurrent requests.

import { createI18nInstance, withI18n } from '@effuse/i18n';

const i18n = createI18nInstance({
	defaultLocale: requestLocale,
	translations: { [requestLocale]: messages },
});

const html = await withI18n(i18n, () => renderApplication());

Public API

• createI18n registers an application-wide instance.
• createI18nInstance creates an isolated instance for SSR or testing.
• withI18n binds an instance to the current runtime context.
• useTranslation exposes reactive translation helpers to components.
• defineTranslations preserves literal keys for type inference.
• t, setLocale, and getLocale access the current bound instance.