Ship multilingual Preact apps with a tiny, typed i18n core

# i18n — integration reference

Type-safe translation lookup, pluralization via Intl.PluralRules, and formatting through native Intl APIs — with an optional Preact adapter and SSR-safe instances.

Package: @kamod-ch/i18n

## Choose an approach

Treat language as part of the application model. Start with complete messages, give every locale the same structure, and keep translation lookup separate from presentation and locale selection.

### A visible message

Define a complete sentence under a stable semantic key.

Avoid stitching translated fragments together; grammar and word order differ.

### Dates, numbers and currencies

Format data with the intended locale using Intl or the documented formatting API.

Keep machine values separate from display strings; a translated number is not a storage format.

### A localized Preact tree

Use I18nProvider and useI18n from the Preact entry point.

Resolve the initial locale once and keep server output and hydration consistent.

## Installation

Install @kamod-ch/i18n for the framework-independent core. Add Preact when using @kamod-ch/i18n/preact.

```bash
pnpm add @kamod-ch/i18n
```

## Starting example

```tsx
import { createI18n, type Messages } from "@kamod-ch/i18n";

const en = { common: { save: "Save" } } as const;
const de = { common: { save: "Speichern" } } satisfies Messages<typeof en>;

const i18n = createI18n({ locale: "en", fallbackLocale: "en", messages: { en, de } });
i18n.t("common.save");
```

### Let the default locale define the shape

Keep keys stable and organize them by meaning. A key such as common.save can be shared where the action means the same thing; two English labels that happen to match do not always need the same translation key.

```tsx
const en = { common: { save: "Save" } } as const;
```

### Check translations while editing

The satisfies check catches structural mistakes in this object. It cannot judge translation quality or whether a sentence fits the screen. Review the full message with a speaker of the target language and test it in context.

```tsx
const de = { common: { save: "Speichern" } } satisfies Messages<typeof en>;
```

### Resolve text at the point of use

The selected locale determines the lookup. In a reactive interface, use the package's Preact integration so changing language updates consumers; do not cache translated labels once at module initialization.

```tsx
i18n.t("common.save"); // "Save" for the starting English locale
```

## Translate complete messages with named values

Let a translator control the whole sentence instead of joining a greeting, name and punctuation in the view. Named interpolation keeps the data separate from the message and gives another language room to reorder the words.

File: src/i18n/messages.ts

```tsx
import { createI18n, type Messages } from "@kamod-ch/i18n";

const en = { dashboard: { welcome: "Welcome {name}" } } as const;
const de = { dashboard: { welcome: "Willkommen {name}" } } satisfies Messages<typeof en>;

export function createMessages(locale: "en" | "de") {
  return createI18n({ locale, fallbackLocale: "en", messages: { en, de } });
}

const messages = createMessages("de");
messages.t("dashboard.welcome", { name: "Alex" });
```

Create the instance for the relevant app or request, then use the same locale for dates, numbers and the document language. Render the result as text. Translation content should not become raw HTML merely because it came from a message file.

## Ownership and environment

Choose one locale owner for the relevant application tree. A language menu, route parameter and saved preference can all contribute to that choice, but they should not compete as independent writable sources. Define their precedence explicitly. Keep a user's language preference separate from assumptions about currency, country or time zone.

For server-rendered pages, create request-specific translation state and carry the resolved locale into the client. Test simultaneous requests in different languages. Use the correct document lang and, when applicable, dir; those attributes affect pronunciation and layout beyond the strings returned by the translator.

A language switch is complete when visible text, accessible labels, formatting and document language agree. Leave room for longer translations instead of fixing controls to English label widths.

## Troubleshooting

### Some labels stay in the old language

Check whether they were translated once outside a reactive consumer. Also inspect accessible names, validation messages and loading text; visible headings alone are not the entire interface.

### The layout breaks in another locale

Try longer translations, narrow widths and larger text. Allow buttons and navigation labels to wrap where appropriate; truncating an essential action can conceal its meaning.

### The server shows another visitor's language

Look for a mutable module-level instance shared across requests. Move locale resolution and instance creation to the request boundary and add a two-locale isolation test.

## Resources

- [Documentation](https://kamod-ch.github.io/kamod-i18n/)
- [Source](https://github.com/kamod-ch/kamod-i18n)
- [npm](https://www.npmjs.com/package/@kamod-ch/i18n)