最佳实践
资源文件组织
建议按以下方式组织资源文件：
locales/
├── en/
│ ├── translation.json # 默认命名空间
│ ├── common.json # 通用翻译
│ └── errors.json # 错误信息
└── zh/
├── translation.json
├── common.json
└── errors.json配置多个命名空间：
export default defineRuntimeConfig({
i18n: {
initOptions: {
ns: ['translation', 'common', 'errors'],
defaultNS: 'translation',
},
},
});使用命名空间：
import { useTranslation } from 'react-i18next';
function MyComponent() {
const { t } = useTranslation('common');
return <div>{t('welcome')}</div>;
}错误处理
建议在资源加载失败时提供回退方案：
检查资源加载状态
当使用 SDK 后端或需要确保资源已加载时，使用 useModernI18n 中的 isResourcesReady：
import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
import { useTranslation } from 'react-i18next';
function MyComponent() {
const { isResourcesReady } = useModernI18n();
const { t } = useTranslation();
// 检查资源是否已加载并准备好
if (!isResourcesReady) {
return <div>正在加载翻译资源...</div>;
}
return <div>{t('content', { defaultValue: 'Default content' })}</div>;
}替代方案：检查 i18next 初始化状态
对于简单场景，也可以检查 i18next 的初始化状态：
import { useTranslation } from 'react-i18next';
function MyComponent() {
const { t, i18n } = useTranslation();
// 检查 i18n 是否已初始化
if (!i18n.isInitialized) {
return <div>Loading...</div>;
}
return <div>{t('content', { defaultValue: 'Default content' })}</div>;
}Tip
对于 SDK 后端场景，isResourcesReady 更准确，因为它会检查所有必需的资源是否实际已加载，而不仅仅是检查实例是否已初始化。
类型安全
为翻译键添加类型定义，提高开发体验：
// types/i18n.d.ts
import 'react-i18next';
declare module 'react-i18next' {
interface CustomTypeOptions {
defaultNS: 'translation';
resources: {
translation: {
hello: string;
world: string;
welcome: string;
};
common: {
submit: string;
cancel: string;
};
};
}
}使用类型安全的翻译：
import { useTranslation } from 'react-i18next';
function MyComponent() {
const { t } = useTranslation();
// TypeScript 会检查键是否存在
return <div>{t('hello')}</div>; // ✅ 类型安全
// return <div>{t('invalid')}</div>; // ❌ TypeScript 错误
}