mirror of
https://github.com/handsomezhuzhu/AeroStart.git
synced 2026-02-20 20:10:15 +00:00
✨ feat: initialize AeroStart browser start page project
Implement a modern, customizable browser start page with comprehensive features: - Multi-theme support with 8 preset color schemes - Custom wallpaper system supporting images and videos with multiple fit modes - Integrated search functionality with 5 major search engines (Google, Baidu, Bing, DuckDuckGo, Bilibili) - Real-time clock component with 12/24 hour format options - Dynamic background blur effect during search for enhanced focus - Complete i18n system with English and Chinese language support - Responsive design with smooth animations and transitions - Local storage integration for persistent user preferences - Context menu system for quick settings access - Toast notification system for user feedback - Error boundary for robust error handling Tech Stack: - React 19 with TypeScript - Vite 6 for build tooling - Tailwind CSS for styling - Local storage for data persistence Project Structure: - Core components: Clock, SearchBox, SettingsModal, ThemeSettings, WallpaperManager - Utility modules: storage management, search suggestions - Context providers: Toast notifications, i18n - Type definitions and constants configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
228
i18n/README.md
Normal file
228
i18n/README.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# 多语言架构使用指南 (i18n Architecture Guide)
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
i18n/
|
||||
├── types.ts # 类型定义
|
||||
├── locales/
|
||||
│ ├── en.ts # 英文翻译
|
||||
│ └── zh.ts # 中文翻译
|
||||
├── I18nContext.tsx # Context 和 Provider
|
||||
├── index.ts # 导出文件
|
||||
└── README.md # 本文档
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 在组件中使用翻译
|
||||
|
||||
```tsx
|
||||
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` 中添加类型定义
|
||||
|
||||
```typescript
|
||||
export interface Translation {
|
||||
// ... 现有的键
|
||||
myNewKey: string;
|
||||
}
|
||||
```
|
||||
|
||||
#### 步骤 2: 在 `locales/en.ts` 中添加英文翻译
|
||||
|
||||
```typescript
|
||||
export const en: Translation = {
|
||||
// ... 现有的翻译
|
||||
myNewKey: 'My New Text',
|
||||
};
|
||||
```
|
||||
|
||||
#### 步骤 3: 在 `locales/zh.ts` 中添加中文翻译
|
||||
|
||||
```typescript
|
||||
export const zh: Translation = {
|
||||
// ... 现有的翻译
|
||||
myNewKey: '我的新文本',
|
||||
};
|
||||
```
|
||||
|
||||
### 3. 在组件中使用新的翻译键
|
||||
|
||||
```tsx
|
||||
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
|
||||
|
||||
如果需要格式化文本,使用多个翻译键:
|
||||
|
||||
```tsx
|
||||
// ❌ 不推荐
|
||||
myKey: '<strong>Bold</strong> text'
|
||||
|
||||
// ✅ 推荐
|
||||
myKeyBold: 'Bold'
|
||||
myKeyText: 'text'
|
||||
|
||||
// 在组件中使用
|
||||
<div><strong>{t.myKeyBold}</strong> {t.myKeyText}</div>
|
||||
```
|
||||
|
||||
### 3. 为长文本使用描述性键名
|
||||
|
||||
```typescript
|
||||
// ✅ 好的命名
|
||||
errorMessage: 'The application encountered an unexpected error...'
|
||||
|
||||
// ❌ 不好的命名
|
||||
error: 'The application encountered an unexpected error...'
|
||||
```
|
||||
|
||||
### 4. 组织相关的翻译键
|
||||
|
||||
在 `Translation` 接口中使用注释分组:
|
||||
|
||||
```typescript
|
||||
export interface Translation {
|
||||
// Common
|
||||
settings: string;
|
||||
appearance: string;
|
||||
|
||||
// Theme Settings
|
||||
themeColor: string;
|
||||
showSeconds: string;
|
||||
|
||||
// Error Messages
|
||||
errorMessage: string;
|
||||
somethingWentWrong: string;
|
||||
}
|
||||
```
|
||||
|
||||
## 🌍 添加新语言
|
||||
|
||||
### 步骤 1: 在 `types.ts` 中添加语言类型
|
||||
|
||||
```typescript
|
||||
export type Language = 'en' | 'zh' | 'ja'; // 添加 'ja' 日语
|
||||
```
|
||||
|
||||
### 步骤 2: 创建新的语言文件
|
||||
|
||||
创建 `locales/ja.ts`:
|
||||
|
||||
```typescript
|
||||
import { Translation } from '../types';
|
||||
|
||||
export const ja: Translation = {
|
||||
settings: '設定',
|
||||
appearance: '外観',
|
||||
// ... 其他翻译
|
||||
};
|
||||
```
|
||||
|
||||
### 步骤 3: 在 `I18nContext.tsx` 中注册新语言
|
||||
|
||||
```typescript
|
||||
const translations: Record<Language, Translation> = {
|
||||
en,
|
||||
zh,
|
||||
ja, // 添加日语
|
||||
};
|
||||
```
|
||||
|
||||
### 步骤 4: 在 `ThemeSettings` 中添加语言选项
|
||||
|
||||
```tsx
|
||||
<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` - 语言偏好持久化
|
||||
|
||||
## 🎉 完成!
|
||||
|
||||
现在你已经了解了如何使用和扩展多语言架构。如果有任何问题,请参考现有组件的实现或查看本文档。
|
||||
Reference in New Issue
Block a user