Get Started
Build an app with Japanese and English messages: define the locales, then render messages from a Server Component and a Client Component.
On this page
Install
npm install @k8ordo/i18nIt runs with:
- TypeScript 7 or later, when you write TypeScript
The guide for AI agents ships at node_modules/@k8ordo/i18n/docs/GUIDE.md. Point your AGENTS.md or the like at that path.
On the server, the runtime must provide AsyncLocalStorage through process.getBuiltinModule. Node 24 does.
Defining the locales
src/i18n.tsimport { defineLocales } from '@k8ordo/i18n';
import type { LocaleOf } from '@k8ordo/i18n';
export const locales = defineLocales({
ja: { timeZone: 'Asia/Tokyo', dir: 'ltr' },
The first locale is the default
en: { timeZone: 'UTC', dir: 'ltr' },
});
declare module '@k8ordo/i18n' {
interface Register {
locale: LocaleOf<typeof locales>;
}
}List the locales the app supports with defineLocales. Each one declares the time zone its dates are shown in (timeZone) and the direction its text runs in (dir).
The Register block tells the package the type of your locales. With it, message requires text for every locale. An @k8ordo/framework app does not write it: the framework generates Register from the locales that src/i18n.ts exports. See @k8ordo/framework’s Routing.
How to choose the default locale and each time zone is covered in Locales.
Defining messages
src/messages/home.tsimport { message } from '@k8ordo/i18n';
export const title = message({ ja: 'ようこそ', en: 'Welcome' });
export const nameLabel = message({ ja: '名前', en: 'Name' });
export const greeting = message({
ja: (name: string) => `こんにちは、${name}さん`,
`name` in `en` is inferred from the annotation on `ja`
en: (name) => `Hello, ${name}`,
});Write each message with message, giving its text in every locale. A message that takes a value is a function in every locale.
The en function takes the same argument types as ja.
Rendering in a Server Component
src/components/welcome.tsximport { title } from '../messages/home';
import { Greeting } from './greeting';
export function Welcome() {
return (
<main>
<h1>{title()}</h1>
Calling it returns the text in the current locale
<Greeting />
</main>
);
}On the server it returns the text in the locale set for the current async context. With none set, it returns the default locale’s text, ようこそ.
locales.run and locales.paramsSchema set it. How to use them is covered in Current locale.
Under @k8ordo/framework, exporting paramsSchema from the [locale] layout renders the pages under /en/… in English. See @k8ordo/framework’s Routing.
Rendering in a Client Component
src/components/greeting.tsx'use client';
import { useState } from 'react';
import { greeting, nameLabel } from '../messages/home';
export function Greeting() {
const [name, setName] = useState('k8o');
return (
<div>
<label>
{nameLabel()}
<input
onChange={(event) => {
setName(event.currentTarget.value);
}}
value={name}
/>
</label>
<p>{greeting(name)}</p>
A message with a value is called with the argument
</div>
);
}A Client Component calls it the same way. In the browser a message reads the first segment of the URL, so there is no provider to pass the locale down and no hook to read it with.
To pass a message from a Server Component to a Client Component as a prop, pass the string you get by calling it. A Server Component cannot pass a function to a Client Component as a prop. See Messages.