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
Define a complete sentence under a stable semantic key.
Avoid stitching translated fragments together; grammar and word order differ.
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.
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.
pnpm add @kamod-ch/i18nCheck 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.
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.
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.
const en = { common: { save: "Save" } } as const;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.
const de = { common: { save: "Speichern" } } satisfies Messages<typeof en>;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.
i18n.t("common.save"); // "Save" for the starting English localeTranslate 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.
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.
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.
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.
# 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)
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.
Keep the Source Close
Look it up, then buildWhen copying or distributing source, retain the applicable license and attribution notices from the version you use.
Good Company for i18n
Three useful connectionsTranslation reaches beyond the message catalog. Connect the language choice, the controls around it and their feedback without making locale state responsible for every preference.
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.
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.