# Internationalization (i18n) Guide This project uses Umi's `plugin-locale` (based on `react-intl`) to manage localization. Translation resources live in `src/locales` (for example `en-US.json`, `zh-CN.json`). Below are instructions for: adding a language, adding a translation entry, switching languages, and disabling i18n. Examples use Japanese `ja-JP`. ## 1. Add a new language (persistent) 1. Create a new translation file under `src/locales/` with the language id as the file name, for example: `src/locales/ja-JP.json`. 2. The file should contain a JSON object of translation keys and values (nesting allowed): ```json { "welcome": "ようこそ", "login": { "username": "ユーザー名", "password": "パスワード", "submit": "ログイン" } } ``` 3. If you want Ant Design components to use the same locale (dates, component text), add the AntD locale import and mapping in `src/app.tsx`'s `pick` function, e.g.: ```ts import jaJP from 'antd/locale/ja_JP'; // ... if (l === 'ja-JP') return jaJP; ``` 4. Add the language to the language selector (for example in `src/components/TopbarControls.tsx`): ```ts { key: 'ja-JP', label: '日本語' } ``` 5. Restart the dev server: ```bash pnpm run dev ``` Umi collects files in `src/locales` into `localeInfo` at build/dev time so the new language becomes available. If you prefer not to restart, see the runtime registration option below. ## 2. Add a translation entry 1. Add the same key to each language JSON (keep `en-US.json` and `zh-CN.json` up to date alongside the new language): `src/locales/en-US.json` ```json "my.feature.greeting": "Hello from feature" ``` `src/locales/zh-CN.json` ```json "my.feature.greeting": "来自功能的问候" ``` 2. In a component use `useIntl()` and `formatMessage`: ```ts import { useIntl } from 'umi'; const intl = useIntl(); const text = intl.formatMessage({ id: 'my.feature.greeting', defaultMessage: 'Hello' }); ``` Use `useIntl()` (or `injectIntl`) so the component updates automatically when the locale changes. ## 3. Runtime switching and registering - Switch locale (writes `umi_locale` to localStorage and either reloads or triggers an update): ```ts import { setLocale } from 'umi'; // switch and reload setLocale('ja-JP', true); // switch without reload (emit update event) setLocale('zh-CN', false); ``` - Register a locale at runtime (no server restart required): ```ts import { addLocale, setLocale } from 'umi'; import jaMessages from '@/locales/ja-JP.json'; import jaAntd from 'antd/locale/ja_JP'; addLocale('ja-JP', jaMessages, { antd: jaAntd, momentLocale: 'ja' }); setLocale('ja-JP', false); ``` `addLocale` merges messages into the internal `localeInfo`. You can pass extra data (like AntD locale and moment locale) so components using AntD/moment behave correctly. ## 4. Disable i18n (turn off multi-language) To permanently disable multi-language support: 1. In `src/app.tsx`'s `LocaleWrapper`, return a fixed AntD locale (ignore `localStorage` `umi_locale`): ```ts const pick = (l: string | null) => { return zhCN; // force Chinese }; ``` 2. Remove or hide the language switcher (for example, remove language menu items in `src/components/TopbarControls.tsx`). 3. Optionally remove other JSON files in `src/locales` except the single target language to reduce build size. If you only want to temporarily prevent user switching, hide the switcher (step 2) and keep files intact for easy re-enable. ## 5. Debugging & common issues - New language not appearing: restart dev server or use `addLocale`; ensure AntD locale mapping exists in `app.tsx`. - Missing translations: check all `src/locales/*.json` contain the key, and the `formatMessage` id is correct. - Want automated extraction of message ids: this repo does not include extraction scripts; consider integrating `lingui`, `babel-plugin-react-intl`, or other tooling and adding scripts to `package.json`. If you want, I can: - create an initial `src/locales/ja-JP.json` and update `TopbarControls`/`app.tsx` mappings; or - add a small example component that demonstrates runtime registration using `addLocale`. Tell me which one you prefer.