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)

Create a new translation file under src/locales/ with the language id as the file name, for example: src/locales/ja-JP.json.
The file should contain a JSON object of translation keys and values (nesting allowed):

{
	"welcome": "ようこそ",
	"login": {
		"username": "ユーザー名",
		"password": "パスワード",
		"submit": "ログイン"
	}
}

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.:

import jaJP from 'antd/locale/ja_JP';
// ...
if (l === 'ja-JP') return jaJP;

Add the language to the language selector (for example in src/components/TopbarControls.tsx):

{ key: 'ja-JP', label: '日本語' }

Restart the dev server:

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

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

"my.feature.greeting": "Hello from feature"

src/locales/zh-CN.json

"my.feature.greeting": "来自功能的问候"

In a component use useIntl() and formatMessage:

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):

import { setLocale } from 'umi';
// switch and reload
setLocale('ja-JP', true);
// switch without reload (emit update event)
setLocale('zh-CN', false);

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:

In src/app.tsx's LocaleWrapper, return a fixed AntD locale (ignore localStorage umi_locale):

const pick = (l: string | null) => {
	return zhCN; // force Chinese
};

Remove or hide the language switcher (for example, remove language menu items in src/components/TopbarControls.tsx).
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.

4.1 KiB Raw Permalink Blame History