最佳实践

资源文件组织

建议按以下方式组织资源文件：

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 错误
}

#最佳实践

#资源文件组织

#错误处理

#检查资源加载状态

#替代方案：检查 i18next 初始化状态