@k8ordo/i18n
v0.1.0
Published
The locale axis of an application, owned. One locale set derives the URL segment, negotiation, the params schema, the static paths, and the current locale on either side of the network; each message is a function that reads it, so a bundler keeps only wha
Maintainers
kosakanokiReadme
@k8ordo/i18n
The locale axis of an application, owned. One locale set declares which
locales exist and which is the default, and derives the URL segment, the
params schema of the [locale] route, negotiation from navigator.languages
or Accept-Language, and the static build's path list. Each message is a
function — message({ ja: 'ホーム', en: 'Home' }) — that reads the locale
where it is called: the request on the server, the URL in the browser. So the
same line renders in a Server Component and in a Client Component, there is
no provider and no hook, and a bundler keeps only the messages a client module
names. No message grammar: interpolation is a template literal and plurals are
Intl.PluralRules.
Like every k8ordo package it assumes React 19 and Server Components, uses only what has reached Baseline newly available, and ships no polyfills or legacy fallbacks.
- Documentation: https://ordo.k8o.me/i18n
- Design guide: docs/GUIDE.md — shipped inside this package
Installation
npm install @k8ordo/i18n
# or
pnpm add @k8ordo/i18nPeer Dependencies
| Package | Version | Needed for |
| ------------ | ------- | ----------------------------- |
| typescript | ≥7.0.2 | the shipped type declarations |
No React import and no schema library: a message is a plain function, and a
locale set is a list that checks membership itself. locales.paramsSchema
speaks Standard Schema, which is what @k8ordo/static and @k8ordo/server
run for a route's params. On a server the current locale rides on
AsyncLocalStorage (Node ≥ 24).
Quick Start
The locale set in its own module, registered once so every message is held to it:
// i18n.ts
import { defineLocales } from '@k8ordo/i18n';
import type { LocaleOf } from '@k8ordo/i18n';
export const locales = defineLocales(['ja', 'en']);
declare module '@k8ordo/i18n' {
interface Register {
locale: LocaleOf<typeof locales>;
}
}Each message is one export, with its text in every locale:
// messages/nav.ts
import { message } from '@k8ordo/i18n';
export const home = message({ ja: 'ホーム', en: 'Home' });
export const greeting = message({
ja: (name: string) => `こんにちは、${name}さん`,
en: (name) => `Hello, ${name}`, // the arguments are typed by ja
});The [locale] route's layout declares the schema; accepting a locale makes it
the locale of that render:
// routes/[locale]/layout.tsx
import { locales } from '../../i18n';
export const paramsSchema = locales.paramsSchema; // /fr/… is a 404And a message is called the same way everywhere:
// routes/[locale]/page.tsx — a Server Component
import * as nav from '../../messages/nav';
export default function Page() {
return <h1>{nav.home()}</h1>;
}// components/toolbar.tsx — a Client Component, the same line
'use client';
import * as nav from '../messages/nav';
export function Toolbar() {
return <button>{nav.greeting('k8o')}</button>;
}Where a Server Component hands text to a Client Component as a prop, it calls the message and passes the string: a function does not cross that boundary.
/ negotiates and redirects; <html lang> and a language switcher read
locales.getLocale(); a static build expands [locale] from locales.all.
AI Agent Documentation
This package ships its documentation so an AI coding assistant reads the exact installed version:
node_modules/@k8ordo/i18n/docs/GUIDE.md— the design guidenode_modules/@k8ordo/i18n/docs/llms.txt— the index
License
MIT