5.2 KiB
Translating the UI
Web uses gt-react, mobile gt-react-native. There is no GT cloud: gt generate scans source for <T>, gt(), msg() and writes committed catalogs keyed by a hash of the English text (apps/{web,mobile}/src/i18n/translations/*.json). Translations are written into those files by hand.
Which API
| Where the text is | Use |
|---|---|
JSX children, including <code>, <strong>, links |
<T>…</T>, values in <Var>, plurals with <Plural n={n} one={…} other={…} /> |
A prop or string inside a component (title, aria-label, tooltips) |
const gt = useGT(), then gt("Discard draft") |
| A constant table (settings index, menus, command registry) | msg("Diagnostics") in the table; const m = useMessages() and m(entry.label) where it renders |
| A helper that builds a label and is called during render | Take a resolve: MessageResolver = m parameter, return resolve(msg(…)); components pass useMessages() |
| Outside React: toasts, stores, announcements, alerts | m(msg("An error occurred.")), m from ~/i18n/messages (mobile: src/i18n/messages) |
m() resolves at call time in the active language and returns English before GT starts, so unit tests keep asserting English without setup. Never call m() during render: the React Compiler caches the result and a language switch would not update it. useGT() and useMessages() re-render on a switch.
Import T, gt, msg and the hooks straight from gt-react or gt-react-native. The CLI only finds strings whose functions are imported from a GT package; a re-export through a local module hides every string behind it, and the next gt generate deletes their keys. Mobile loads the Intl polyfills GT needs at the top of index.ts, so direct imports are safe.
Code in packages/client-runtime and packages/shared is scanned by both apps (src in each gt.config.json) and marks strings with msg() from gt-i18n. Its helpers take resolve: MFunctionType = mFallback, and mFallback always returns English: apps pass useMessages() in render or m elsewhere, and key caches and effects on useLocale(), not on the resolver.
The server imports packages/shared and stays English, so a server-imported module keeps its English and its translatable copy lives in a *Copy sibling only clients import (usageLimits.ts and usageLimitsCopy.ts).
Writing strings
- Variables:
gt("{shortcut} to undo", { shortcut }). The English text in the source must not change by one character: the hash is the key, and tests assert on it. - Plurals:
gt("{count, plural, one {{count} thread} other {{count} threads}}", { count }). Use{count}, not#:#formats 1234 as "1,234" and changes the English. When the singular has no number ("View browser"), use=1 {…}. - ICU syntax: an ASCII apostrophe next to
{or}starts a quote, so write''{name}''to print'name'. Literal braces need'{'. Never put tags ingt()text; markup goes in<T>. $contextdisambiguates short words that translate differently:gt("Open", { $context: "verb, opens a file" })vsgt("Open", { $context: "pull request state" }). Add it to any one- or two-word label whose part of speech is not obvious.- Split nothing. One sentence is one string, with variables inside it. Never build a sentence from translated fragments.
- The same English in
gt()and in<T>is two keys. That is fine.
What stays English
Product and provider names (Hanzo Dev, Codex, Claude, GitHub), model ids, code, commands, file paths, URLs, keybinding glyphs and key names, user content, agent prompts and anything sent to an agent, log and console output, and text authored by the server (errors, activity labels, provider status). Wrap the sentence around them and pass them as variables.
Dates and numbers
timestampFormat.ts formats times in the host's regional locale with the user's 12/24-hour setting; keep that. Words around them ("just now", "5m ago", "Expires in") are strings and follow the rules above.
Regenerating catalogs
Run vp run i18n:generate in apps/web and in apps/mobile after wrapping strings (about 20 s, offline). It adds new keys to every locale with the English text as the value and drops keys no longer in source. An untranslated key renders English but uses the target language's plural rules. Do not edit en.json by hand.
The desktop main process has its own catalogs in apps/desktop/src/i18n/translations, regenerated with vp run i18n:generate in apps/desktop.
hanzo/no-untranslated-copy reports unwrapped copy as an error. vp run i18n:untranslated at the repo root counts what it flags, per directory. For English that stays English and the rule still flags, write // oxlint-disable-next-line hanzo/no-untranslated-copy -- <why>.