Kernlift

Add and change copy

Edit copy in English and Chinese, add a locale-aware route, and understand the optional locale segment and the i18n validators.

Every page ships in English and Simplified Chinese from one route file. English is served without a prefix (/pricing), Chinese under /zh (/zh/pricing). Components contain no copy. Copy comes from a dictionary, and both locales carry the same keys.

Before you begin

Know where copy lives

StoreFilesRead with
The main dictionariessrc/i18n/locales/en/messages.ts and src/i18n/locales/zh/messages.tst("shell.nav.dashboard") from useI18n() or getDictionary(locale), or a whole namespace with getMessageNamespace(locale, "publicSite")
Feature copy filessrc/i18n/*.ts, for example admin-plans.ts, auth-pages.ts, system-pages.tsThe exported table indexed by locale: adminEditingMessages[locale]

Both hold the same kind of data. The main dictionaries carry shared and public copy and every navigation label. A feature file keeps the copy of one console area next to its types. Use whichever the code you are editing already uses.

The helpers are all in src/i18n/messages.ts:

HelperUse
locales, defaultLocale["en", "zh"] and "en"
normalizeLocale(value)Turns a route param into a Locale; anything unknown becomes en
localizedPath(path, locale)/pricing for en, /zh/pricing for zh. Build every internal link with it
switchLocalePath(path, locale)The same page in another locale; the language switcher uses it
getDictionary(locale){ locale, t } outside a route component
getMessageNamespace(locale, key)One top-level namespace as a typed object, including arrays and formatter functions
localeToIntlTag(locale)en-US or zh-CN for Intl number and date formatting

Change existing copy

Find the key

Search both messages.ts files and src/i18n/ for the English text you see on the page. Public and shared copy is in the main dictionaries; console copy may be in a feature file.

Edit the same key in both locales

Change the value under the same path in the English and the Chinese entry. Values are strings, arrays, or functions for text with a number in it:

src/i18n/locales/en/messages.ts
pricing: {
  title: "Plans",
  credits: (count: number) => `${count.toLocaleString("en-US")} credits included`,
},

Do not rename a key to change its text, because other files may read it.

Add new copy

Add the keys to both dictionaries

For a few strings, add them to an existing namespace. For a new page or feature, add a namespace of its own, at the same position in both files:

src/i18n/locales/en/messages.ts
reportsPage: {
  title: "Reports",
  empty: "No reports yet.",
},
src/i18n/locales/zh/messages.ts
reportsPage: {
  title: "报表",
  empty: "还没有报表。",
},

Keys inside a module's // @module:<key> region belong to that module. Put your own keys outside those regions.

Read them in the component

Inside a route component under {-$locale}:

import { useI18n } from "@/i18n/use-i18n";

const { locale, t } = useI18n();
return <h1>{t("reportsPage.title")}</h1>;

In a component that receives locale as a prop, read the namespace:

import { getMessageNamespace, type Locale } from "@/i18n/messages";

const copy = getMessageNamespace(locale, "reportsPage");

t() is typed against the English dictionary, so a misspelt key fails pnpm typecheck. At runtime a key that is missing from the Chinese dictionary renders as the key itself.

Check that both dictionaries have the same keys

pnpm validate:app-i18n

The dictionaries-carry-the-same-keys check runs validateLocaleParity(), which compares every key path. It fails and lists the keys when one locale has a key the other lacks.

Add a locale-aware route

Create the file under {-$locale}

Every page route lives in src/routes/{-$locale}/. {-$locale} is TanStack Router's optional path segment. The same file serves /reports with no locale param and /zh/reports with locale: "zh".

src/routes/{-$locale}/reports.tsx
import { createFileRoute } from "@tanstack/react-router";
import { normalizeLocale } from "@/i18n/messages";

export const Route = createFileRoute("/{-$locale}/reports")({
  component: ReportsPage,
});

function ReportsPage() {
  const { locale } = Route.useParams();
  return <ReportsView locale={normalizeLocale(locale)} />;
}

Do not create a src/routes/zh/ tree or a second file per language. pnpm validate:route-i18n fails on either.

Let the parent route handle unknown locales

src/routes/{-$locale}.tsx is the parent of every page. It returns not found for a first segment that is not a known locale and puts the resolved locale into the route context, which useI18n() reads. You do not repeat that check in a page.

Build links with localizedPath(). For a public page, pass the localized path to buildMeta() and add hreflang alternates, as buildHomeHead() in src/components/marketing/example-landing.tsx does. The root document sets <html lang> from the URL (en or zh-Hans) on its own.

Regenerate the route tree

Run pnpm dev once. It rewrites src/routeTree.gen.ts to include the new route. pnpm typecheck fails until it does.

Know what the validators check

ValidatorWhat it asserts about i18n
pnpm validate:route-i18nEvery page route is under src/routes/{-$locale}/; no src/routes/zh/ files exist; the parent route validates the locale; the home page is one route around one shared component
pnpm validate:app-i18nThe shells, navigation labels, auth, system, setup and public pages read their copy from the dictionaries; navigation entries carry a labelKey; listed strings are not hard-coded
pnpm validate:beui-consoleEach console copy file in src/i18n/ (names starting with admin, asset, email, support, auth, system, billing or config) has en and zh entries with identical keys, and no other locale
pnpm validate:systemThe system state pages and their copy

pnpm validate:app-i18n also compares the key sets of the main dictionaries and names any key that exists in only one locale.

Adding a third locale

The locale list is the locales constant in src/i18n/messages.ts, with a dictionary per entry and tags in localeHrefLang and localeToIntlTag. The console copy files and pnpm validate:beui-console accept en and zh only, so adding a third locale requires changing those files and that validator.

Verify

pnpm typecheck
pnpm validate:route-i18n
pnpm validate:app-i18n
pnpm validate:beui-console

Open the page at its English path and under /zh. Use the language switcher on the page. It opens the same page in the other language, and every label changes.

Next steps