Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

kamod-i18n · Typed Keys · Zero Runtime Deps

Ship Multilingual Preact Apps with a Tiny, Typed i18n Core

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

Build around One Default Locale and a Clear Message Schema. Translate complete messages, keep formatting locale-aware, and plan how the selected language reaches both your server-rendered document and your Preact tree. Pair it with the Component Library when building your interface. Continue with the Full Documentation for the complete package reference.


What the Package Brings

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.

Choose the Right Approach

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.

Default-Locale-as-Schema

Nested translation keys are inferred from your default locale so typos fail at compile time.

Group messages around a screen or task, such as common actions or checkout errors. Add a key to the default locale first, then supply the corresponding translations so changes remain easy to review together.

Preact-Native Adapter

I18nProvider and useI18n live in @kamod-ch/i18n/preact without React compatibility layers.

Place the provider around the tree that shares a language. Translate the visible label and its accessible name together; switching languages should not leave controls with mixed-language instructions.

SSR-Safe Core

Create one i18n instance per request — no global mutable locale state leaking across users.

Resolve the locale at the request boundary and reuse that choice during hydration. Test two requests with different languages to catch accidental shared state before deploying.

Installation

Start with the translation core. Install @kamod-ch/i18n for message lookup and locale-aware formatting without tying that code to a UI framework. For reactive Preact components, also provide Preact and import the adapter from @kamod-ch/i18n/preact; the adapter is included in the same package.

Keep the first setup easy to verify. Prepare one default locale and one additional language, then try the Usage Example before adding lazy loading or persisted language preferences. If your app renders on the server, plan the instance boundary using Account for the Environment.

Install PackagesTerminal
pnpm add @kamod-ch/i18n

Check Your Environment

Use your existing package manager and keep the peer dependencies aligned with your application. Compare package.json and your lockfile with the documentation for the version you install; add the package once at the workspace boundary that uses it.

Keep the First Change Small. Start with the usage example, run your project’s typecheck and build, then connect it to a real screen. The Package Overview helps you decide how companion libraries fit together.

Usage

Let the default language define the message shape. Create the translation instance with createI18n and your locale objects, and use satisfies Messages<typeof en> to check that another language has the expected structure. The first example looks up a complete message by its stable key, keeping translation content separate from component markup.

Connect language changes to the interface. For Preact consumers, pair I18nProvider with useI18n through the adapter and consult the API Reference for reactive locale updates. The Named Values Example shows how to insert data without joining sentence fragments. When switching languages, also review document language, accessible labels and formatting in the Accessibility Notes.

src/example.tsx7 lines
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");

Read the Example

Follow the value from its definition to the interface. Each part below explains a decision to keep when adapting the example.

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.

Usage PatternTypeScript
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.

Usage PatternTypeScript
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.

Usage PatternTypeScript
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.

src/i18n/messages.ts11 lines
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" });

Try the Boundaries. 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.

Integrate with Your Application

Organize Messages by the Task They Describe. Group labels, hints and validation messages together so a form can be translated as a coherent experience. Keep user-facing strings out of rendering branches where they are easy to miss.

Allow room for longer translations in buttons, navigation and empty states. Prefer complete messages over concatenated fragments, and use locale-aware formatting for dates and numbers instead of building display strings manually.

Create request-specific instances on the server and pass the same starting locale to the client. When language changes, review document lang, translated accessible names and any region whose reading direction changes.

Choose the Owner and Lifetime

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.

Account for the Environment

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.

Connect the Pieces. Forms and Validation — Include validation errors, field instructions and submit feedback in your message schema, not only navigation labels.

Integration goal
What a good integration looks like

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.

When Something Behaves Differently

Start with the smallest failing interaction. Compare a fresh page with the same page after a change or reload, and keep the package version in your reproduction.

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.

If the behavior still differs from the documented API, Check Existing Issues before opening a report. Include the expected result, actual result, package version and a small reproduction without private application data.

API Reference

This page is a Kamod UI overview. Full API docs, lazy locale loading, plural rules, and SSR guides live on the dedicated kamod-i18n docs.

Use this page to understand the integration, then consult the Full API Reference on Live Docs for exact signatures and supported options. Compare those details with the version in your lockfile before adapting an example.

Browse Guides, API, and Preact Examples

Open the kamod-i18n docs for getting started, lazy locales, pluralization, and SSR patterns.

  • Before Choosing an API: read its input types, return values and default behavior.
  • Before Shipping: review lifecycle or server-rendering notes for the features you use.
  • When Behavior Differs: reduce the case to a small example and include your package version in the report.
Continue with the dedicated package documentation.Open Live Docs

Accessibility Notes

When switching locale, update lang on the document or region root and keep translated strings in accessible names, labels, and live regions.

Before You Ship

  • Check a missing translation and confirm that the intended fallback is understandable.
  • Try long labels, plural messages and locale-specific dates and numbers.
  • Reload a translated route and verify that the first render and accessible labels use the selected language.

Review the result with Real Content and Keyboard Input. Keep visible labels, loading and error feedback, and focus behavior in sync with the state your application exposes.

Take the Guide with You

Keep the Examples, Integration Decisions and Troubleshooting Notes together in your project, or share them with a coding assistant. This reference works with any assistant; no model-specific setup is needed. Check the installed version and your project’s conventions before applying a suggestion.

Keep It HandyReady for your project
DownloadMarkdown
i18n-package-reference.md163 lines
# 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

**Start with the translation core.** Install `@kamod-ch/i18n` for message lookup and locale-aware formatting without tying that code to a UI framework. For reactive Preact components, also provide Preact and import the adapter from `@kamod-ch/i18n/preact`; the adapter is included in the same package.

**Keep the first setup easy to verify.** Prepare one default locale and one additional language, then try the [Usage Example](https://ui.kamod.ch/docs/i18n-package/installation#usage) before adding lazy loading or persisted language preferences. If your app renders on the server, plan the instance boundary using [Account for the Environment](https://ui.kamod.ch/docs/i18n-package/installation#environment-boundaries).

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

## Starting example

**Let the default language define the message shape.** Create the translation instance with `createI18n` and your locale objects, and use `satisfies Messages<typeof en>` to check that another language has the expected structure. The first example looks up a complete message by its stable key, keeping translation content separate from component markup.

**Connect language changes to the interface.** For Preact consumers, pair `I18nProvider` with `useI18n` through the adapter and consult the [API Reference](https://ui.kamod.ch/docs/i18n-package/installation#api-reference) for reactive locale updates. The [Named Values Example](https://ui.kamod.ch/docs/i18n-package/installation#put-it-to-work) shows how to insert data without joining sentence fragments. When switching languages, also review document language, accessible labels and formatting in the [Accessibility Notes](https://ui.kamod.ch/docs/i18n-package/installation#accessibility).

```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

- [Dedicated documentation](https://kamod-ch.github.io/kamod-i18n/) — Exact signatures, supported options and deeper examples.

- [Source & release history](https://github.com/kamod-ch/kamod-i18n) — Implementation, release notes and the project’s issue tracker.

- [Published package](https://www.npmjs.com/package/@kamod-ch/i18n) — Compare the version and peer requirements with your lockfile.

When copying or distributing source, retain the applicable license and attribution notices from the version you use.

## Companion packages

Translation reaches beyond the message catalog. Connect the language choice, the controls around it and their feedback without making locale state responsible for every preference.

### Signals — Remember the language choice

[`@kamod-ch/signals`](https://ui.kamod.ch/docs/signals-package/installation)

Persist a validated locale preference when it should survive a visit. Decide how a saved choice interacts with a route or account setting; persistence supplies a value, not your application’s locale precedence or server request isolation.

### Icons — Make the language menu legible

[`@kamod-ch/icons`](https://ui.kamod.ch/docs/icons-package/installation)

Pair a language symbol with the language’s own name rather than relying on a flag. Keep the name readable at narrow widths and give icon-only controls translated accessible labels; an icon family does not determine text direction.

### Hooks — Localize the whole interaction

[`@kamod-ch/hooks`](https://ui.kamod.ch/docs/hooks-package/installation)

A counter or async interaction needs translated limits, pending feedback and errors as well as its button label. Keep the raw value and request state separate from formatted text, then render those messages through the active locale.

## Try a second language on a real screen.

Take one form from its field instructions through validation and success feedback. Use a longer translation and a right-to-left locale to find assumptions that a short navigation label would miss.

[Review direction-aware UI](https://ui.kamod.ch/docs/direction/installation)

Check document lang, the relevant dir boundary and the server-to-client locale handoff.

[All packages](https://ui.kamod.ch/docs/packages) · [The wider ecosystem](https://ui.kamod.ch/docs/ecosystem)
Display changes only the view. Copy and download include the complete Markdown reference.

Sources & Attribution

This integration guide accompanies @kamod-ch/i18n, maintained in the Kamod ecosystem. The Dedicated Documentation is the reference for package APIs; examples here show how those APIs fit into a Kamod UI application.

Try a Second Language on a Real Screen.

Take one form from its field instructions through validation and success feedback. Use a longer translation and a right-to-left locale to find assumptions that a short navigation label would miss.

Check document lang, the relevant dir boundary and the server-to-client locale handoff.

Take the Next Useful Step

You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.

Connect the Foundation

Return to Choose Your Companion Packages to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.

Build the Surrounding Screen

Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.

Make the Result Hold Up

Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.

Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.