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
- A project that runs with
pnpm dev. - The text in both languages. A key that exists in one dictionary only is a bug, even when the page looks fine in the language you are testing.
- For a whole new page, follow Add an admin or workspace page or Replace the landing and pricing pages. This guide covers the copy and routing they rely on.
Know where copy lives
| Store | Files | Read with |
|---|---|---|
| The main dictionaries | src/i18n/locales/en/messages.ts and src/i18n/locales/zh/messages.ts | t("shell.nav.dashboard") from useI18n() or getDictionary(locale), or a whole namespace with getMessageNamespace(locale, "publicSite") |
| Feature copy files | src/i18n/*.ts, for example admin-plans.ts, auth-pages.ts, system-pages.ts | The 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:
| Helper | Use |
|---|---|
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:
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:
reportsPage: {
title: "Reports",
empty: "No reports yet.",
},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-i18nThe 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".
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.
Link and describe the page per locale
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
| Validator | What it asserts about i18n |
|---|---|
pnpm validate:route-i18n | Every 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-i18n | The 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-console | Each 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:system | The 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-consoleOpen 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
Use the design system
Build or restyle a screen with beUI, the motion components and the product tokens, change the theme, and avoid the imports the validators reject.
Add an admin or workspace page
Add one screen under /admin or /app with a guarded server function, copy in both locales and a navigation entry.