LobeHub Internationalization Guide Skill

LobeHub Internationalization Guide

Default language: English (en-US)
Framework: react-i18next
Only edit files in packages/locales/src/default/ - Never hand-write translations in locales/ JSON (except en-US/zh-CN previews); generated locales change only through lobe-i18n, plus the key deletions described in Changing an existing key's English text
Leave generated locales to the daily auto-i18n.yml workflow by default; run bun run i18n manually only when they are needed immediately

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 packages/locales/src/default/{namespace}.ts
Export new namespace in packages/locales/src/default/index.ts
For dev preview: manually translate locales/zh-CN/{namespace}.json and locales/en-US/{namespace}.json
Leave all other locales to .github/workflows/auto-i18n.yml, which runs daily and opens an automated translation PR
Run bun run i18n manually only when the branch needs those translations immediately; it is slow and requires OPENAI_API_KEY

Changing an existing key's English text

lobe-i18n (both the daily workflow and bun run i18n) only translates keys that are missing from a locale. It never re-translates a key whose English value changed, so editing an existing value leaves every generated locale on the old text indefinitely (e.g. expanded settingsSearch.tabKeywords.* stayed stale in 16 locales for weeks).

When a change alters an existing key's meaning or content (not just a typo), do one of:

Rename the key, so it is missing everywhere and gets translated fresh.
Re-translate it in the same PR: delete the key from every generated locales/*/{namespace}.json (all except en-US/zh-CN), run bun run i18n, and commit only those keys — the run also fills unrelated missing keys, which belong to the daily workflow PR.
If the stale translation is harmless until the daily run, delete the key from the generated locales so they fall back to English and the workflow re-translates it. Do not do this when the localized text is load-bearing (e.g. search keywords users type in their own language).

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

Agent Skills: LobeHub Internationalization Guide

Install this agent skill to your local

Skill Files