i18n
lobehub/lobe-chat
Manage multilingual UI strings in LobeHub using react-i18next with flat key conventions.
What is i18n?
This skill guides you through LobeHub's internationalization (i18n) setup using react-i18next. Use it when adding or updating user-facing strings, managing locale keys across namespaces, or preparing translations for zh-CN and en-US.
- Add and organize translation keys using flat dot-notation (e.g., 'feature.context.action')
- Use the useTranslation hook and t() function to retrieve translated strings in React components
- Support parameter interpolation with {{variableName}} syntax for dynamic content
- Manage multiple namespaces (common, chat, setting, auth, etc.) for organized translations
- Generate translations via pnpm i18n command or manually edit locale JSON files for dev preview
- Avoid key conflicts by following consistent naming patterns
How to install i18n
npx skills add https://github.com/lobehub/lobe-chat --skill i18n- LobeHub project cloned and dependencies installed (pnpm)
- Familiarity with React and hooks
- Access to src/locales/default/ directory for editing translation files
How to use i18n
- 1.Create or edit a namespace file in src/locales/default/ (e.g., src/locales/default/common.ts) using flat dot-notation keys
- 2.Export the new namespace in src/locales/default/index.ts if it's new
- 3.For dev preview, manually add translations to locales/zh-CN/{namespace}.json and locales/en-US/{namespace}.json
- 4.In your React component, import useTranslation and call const { t } = useTranslation('namespace')
- 5.Use t('key') or t('key', { param: value }) to retrieve translated strings in JSX
- 6.Before creating a PR, remind the user to run pnpm i18n to generate all translations (do not run it yourself)
Use cases
- Adding new UI copy to a feature and ensuring it's translated to both English and Chinese
- Updating hardcoded strings in components to use translation keys
- Creating parameterized messages that insert dynamic values (e.g., credit amounts, user names)
- Setting up translations for a new namespace before running the build pipeline
- Previewing Chinese and English versions of UI strings during development
- Frontend developers building features in LobeHub
- UI/UX designers preparing copy for multilingual interfaces
- Contributors adding new locales or updating existing translations
- Teams maintaining consistent messaging across zh-CN and en-US versions
i18n FAQ
Use flat keys with dot notation following the pattern {feature}.{context}.{action|status}, e.g., 'alert.cloud.action'. Avoid nested objects and ensure keys don't conflict by being specific (e.g., 'clientDB.solve.action' instead of 'clientDB.solve').
Use {{variableName}} syntax in your translation value, e.g., 'alert.cloud.desc': '我们提供 {{credit}} 额度积分'. Then pass the variable when calling t(): t('alert.cloud.desc', { credit: '1000' }).
Only edit files in src/locales/default/. Never directly edit JSON files in the locales/ directory—those are generated. For dev preview, you may manually edit locales/zh-CN/ and locales/en-US/ JSON files.
Import useTranslation from 'react-i18next', call const { t } = useTranslation('namespace'), and use t('key') in your JSX. For multiple namespaces, pass an array: useTranslation(['common', 'chat']), then use t('common:key').
Run pnpm i18n before creating a PR to generate all translations. Do not run it during development—manually edit locale JSON files for preview instead.
Full instructions (SKILL.md)
Source of truth, from lobehub/lobe-chat.
name: i18n description: 'LobeHub i18n with react-i18next. Use for user-facing strings, locale keys, namespaces, useTranslation, t(), interpolation, zh-CN/en-US previews, hardcoded UI copy, or pnpm i18n.' user-invocable: false
LobeHub Internationalization Guide
- Default language: English (en-US)
- Framework: react-i18next
- Only edit files in
src/locales/default/- Never edit JSON files inlocales/ - Run
pnpm i18nto generate translations (or manually translate zh-CN/en-US for dev preview)
Key Naming Convention
Flat keys with dot notation (not nested objects):
// ✅ Correct
export default {
'alert.cloud.action': '立即体验',
'sync.actions.sync': '立即同步',
'sync.status.ready': '已连接',
};
// ❌ Avoid nested objects
export default {
alert: { cloud: { action: '...' } },
};
Patterns: {feature}.{context}.{action|status}
Parameters: Use {{variableName}} syntax
'alert.cloud.desc': '我们提供 {{credit}} 额度积分',
Avoid key conflicts:
// ❌ Conflict
'clientDB.solve': '自助解决',
'clientDB.solve.backup.title': '数据备份',
// ✅ Solution
'clientDB.solve.action': '自助解决',
'clientDB.solve.backup.title': '数据备份',
Workflow
- Add keys to
src/locales/default/{namespace}.ts - Export new namespace in
src/locales/default/index.ts - For dev preview: manually translate
locales/zh-CN/{namespace}.jsonandlocales/en-US/{namespace}.json - Remind the user to run
pnpm i18nbefore creating PR — do NOT run it yourself (very slow)
Usage
import { useTranslation } from 'react-i18next';
const { t } = useTranslation('common');
t('newFeature.title');
t('alert.cloud.desc', { credit: '1000' });
// Multiple namespaces
const { t } = useTranslation(['common', 'chat']);
t('common:save');
Common Namespaces
Most used: common (shared UI), chat (chat features), setting (settings)
Others: auth, changelog, components, discover, editor, electron, error, file, hotkey, knowledgeBase, memory, models, plugin, portal, providers, tool, topic
Related skills
More from lobehub/lobe-chat and the wider catalog.
