AeroStart/i18n

多语言架构使用指南 (i18n Architecture Guide)

📁 项目结构

i18n/
├── types.ts              # 类型定义
├── locales/
│   ├── en.ts            # 英文翻译
│   └── zh.ts            # 中文翻译
├── I18nContext.tsx      # Context 和 Provider
├── index.ts             # 导出文件
└── README.md            # 本文档

🚀 快速开始

1. 在组件中使用翻译

import { useTranslation } from '../i18n';

const MyComponent = () => {
  const { t, language, setLanguage } = useTranslation();

  return (
    <div>
      <h1>{t.settings}</h1>
      <p>{t.appearance}</p>
      <button onClick={() => setLanguage('zh')}>切换到中文</button>
    </div>
  );
};

2. 添加新的翻译键

步骤 1: 在 types.ts 中添加类型定义

export interface Translation {
  // ... 现有的键
  myNewKey: string;
}

步骤 2: 在 locales/en.ts 中添加英文翻译

export const en: Translation = {
  // ... 现有的翻译
  myNewKey: 'My New Text',
};

步骤 3: 在 locales/zh.ts 中添加中文翻译

export const zh: Translation = {
  // ... 现有的翻译
  myNewKey: '我的新文本',
};

3. 在组件中使用新的翻译键

const MyComponent = () => {
  const { t } = useTranslation();

  return <div>{t.myNewKey}</div>;
};

📝 已支持的语言

• English (en) - 英语
• 简体中文 (zh) - Simplified Chinese

🎯 已翻译的组件

以下组件已经集成了多语言支持：

• ✅ ThemeSettings - 主题设置（包含语言切换器）
• ⏳ SettingsModal - 设置模态框（待更新）
• ⏳ SearchBox - 搜索框（待更新）
• ⏳ SearchEngineManager - 搜索引擎管理器（待更新）
• ⏳ WallpaperManager - 壁纸管理器（待更新）
• ⏳ GlobalContextMenu - 全局右键菜单（待更新）
• ⏳ ErrorBoundary - 错误边界（待更新）
• ⏳ Clock - 时钟（待更新）

🔧 API 参考

useTranslation() Hook

返回一个包含以下属性的对象：

• t: Translation - 当前语言的翻译对象
• language: Language - 当前语言 ('en' | 'zh')
• setLanguage: (lang: Language) => void - 切换语言的函数

I18nProvider Component

Props:

• language: Language - 当前语言
• onLanguageChange: (lang: Language) => void - 语言变化回调
• children: ReactNode - 子组件

💡 最佳实践

1. 保持翻译键的一致性

使用描述性的键名，例如：

• ✅ searchEngineDeleted
• ❌ msg1

2. 避免在翻译中使用 HTML

如果需要格式化文本，使用多个翻译键：

// ❌ 不推荐
myKey: '<strong>Bold</strong> text'

// ✅ 推荐
myKeyBold: 'Bold'
myKeyText: 'text'

// 在组件中使用
<div><strong>{t.myKeyBold}</strong> {t.myKeyText}</div>

3. 为长文本使用描述性键名

// ✅ 好的命名
errorMessage: 'The application encountered an unexpected error...'

// ❌ 不好的命名
error: 'The application encountered an unexpected error...'

4. 组织相关的翻译键

在 Translation 接口中使用注释分组：

export interface Translation {
  // Common
  settings: string;
  appearance: string;

  // Theme Settings
  themeColor: string;
  showSeconds: string;

  // Error Messages
  errorMessage: string;
  somethingWentWrong: string;
}

🌍 添加新语言

步骤 1: 在 types.ts 中添加语言类型

export type Language = 'en' | 'zh' | 'ja'; // 添加 'ja' 日语

步骤 2: 创建新的语言文件

创建 locales/ja.ts:

import { Translation } from '../types';

export const ja: Translation = {
  settings: '設定',
  appearance: '外観',
  // ... 其他翻译
};

步骤 3: 在 I18nContext.tsx 中注册新语言

const translations: Record<Language, Translation> = {
  en,
  zh,
  ja, // 添加日语
};

步骤 4: 在 ThemeSettings 中添加语言选项

<button onClick={() => handleLanguageChange('ja')}>
  日本語
</button>

🐛 故障排除

问题：翻译不显示

解决方案：

1. 确保组件在 I18nProvider 内部
2. 检查是否正确导入了 useTranslation
3. 验证翻译键在所有语言文件中都存在

问题：TypeScript 错误

解决方案：

1. 确保所有语言文件都实现了 Translation 接口
2. 运行 npx tsc --noEmit 检查类型错误
3. 确保新添加的键在 types.ts 中有定义

📚 相关文件

• types.ts - UserSettings 类型（包含 language 字段）
• App.tsx - I18nProvider 集成
• utils/storage.ts - 语言偏好持久化

🎉 完成！

现在你已经了解了如何使用和扩展多语言架构。如果有任何问题，请参考现有组件的实现或查看本文档。