为 TimeLens 添加新语言

TimeLens 使用 i18next 进行国际化管理。添加一种新语言只需翻译 JSON 文件并在配置中注册即可，无需修改任何业务代码。

翻译文件结构

每种语言在 src/i18n/locales/{语言代码}/ 目录下拥有独立的 JSON 文件，按功能域拆分：

src/i18n/locales/
├── en/
│   ├── common.json
│   ├── dashboard.json
│   ├── widgets.json
│   ├── settings.json
│   ├── categories.json
│   ├── limits.json
│   ├── goals.json
│   ├── focus.json
│   └── browserUsage.json
├── zh-CN/
│   └── (同上)
└── ja/          ← 你的新语言
    ├── common.json
    ├── dashboard.json
    ├── widgets.json
    ├── settings.json
    ├── categories.json
    ├── limits.json
    ├── goals.json
    ├── focus.json
    └── browserUsage.json

Step 1 — 创建翻译文件

复制 src/i18n/locales/en/ 目录作为模板，重命名为目标语言代码（如 ja、de、fr 等）。

重要：只翻译 JSON 的 值（value），不要翻译 键（key）。键名在代码中被直接引用。

common.json 示例

// src/i18n/locales/ja/common.json
{
  "appName": "TimeLens",
  "loading": "読み込み中…",
  "error": "エラー",
  "hours": "時間",
  "minutes": "分",
  "seconds": "秒",
  "today": "今日",
  "yesterday": "昨日",
  "tracking": "追跡中",
  "paused": "一時停止",
  "save": "保存",
  "cancel": "キャンセル",
  "delete": "削除",
  "edit": "編集",
  "add": "追加",
  "search": "検索",
  "noData": "データがありません",
  "confirm": "確認",
  "close": "閉じる"
}

dashboard.json 关键键说明

键名	上下文
`title`	仪表盘页面标题
`todayOverview`	今日概览卡片标题
`appRanking`	应用排行卡片标题
`hourlyDistribution`	小时分布图表标题
`usageHeatmap`	使用热力图标题
`productivityScore`	生产力评分标题
`goalProgress`	目标进度标题
`trendCompare`	趋势对比标题
`categoryInsights`	分类洞察标题
`customizeTitle`	布局自定义页面标题

Step 2 — 注册到 i18n 配置

打开 src/i18n/config.ts，在文件顶部添加新语言的 import：

// 添加以下导入（以 ja 为例）
import jaCommon        from "./locales/ja/common.json";
import jaDashboard     from "./locales/ja/dashboard.json";
import jaWidgets       from "./locales/ja/widgets.json";
import jaSettings      from "./locales/ja/settings.json";
import jaCategories    from "./locales/ja/categories.json";
import jaLimits        from "./locales/ja/limits.json";
import jaGoals         from "./locales/ja/goals.json";
import jaFocus         from "./locales/ja/focus.json";
import jaBrowserUsage  from "./locales/ja/browserUsage.json";

Step 3 — 添加到 resources

在同一个文件中找到 i18next.init 的 resources 对象，添加新语言：

resources: {
  en: {
    common: enCommon,
    dashboard: enDashboard,
    widgets: enWidgets,
    settings: enSettings,
    categories: enCategories,
    limits: enLimits,
    goals: enGoals,
    focus: enFocus,
    browserUsage: enBrowserUsage,
  },
  "zh-CN": { /* ... */ },
  // ↓ 添加你的语言
  ja: {
    common: jaCommon,
    dashboard: jaDashboard,
    widgets: jaWidgets,
    settings: jaSettings,
    categories: jaCategories,
    limits: jaLimits,
    goals: jaGoals,
    focus: jaFocus,
    browserUsage: jaBrowserUsage,
  },
},

Step 4 — 注册到支持语言列表

在同一文件中，找到 SUPPORTED_LANGUAGES 数组并添加：

export const SUPPORTED_LANGUAGES = [
  { code: "en",    label: "English" },
  { code: "zh-CN", label: "中文（简体）" },
  // ↓ 添加你的语言
  { code: "ja",    label: "日本語" },
] as const;

Step 5 — 翻译系统托盘菜单

系统托盘菜单文本在 Rust 层硬编码，需要修改 src-tauri/src/lib.rs：

fn tray_texts(lang: &str, is_active: bool) -> TrayTexts {
    let zh = lang.starts_with("zh");
    let ja = lang.starts_with("ja");  // 添加语言检测

    if ja {
        TrayTexts {
            show: "TimeLens を開く",
            new_clock: "新しい時計ウィジェット",
            new_todo: "新しい ToDo ウィジェット",
            new_timer: "新しいタイマーウィジェット",
            pause_or_resume: if is_active { "記録を一時停止" } else { "記録を再開" },
            quit: "終了",
        }
    } else if zh {
        // ...
    } else {
        // English default
    }
}

Step 6 — 测试验证

完成以上步骤后，启动开发服务器验证：

npm run tauri:dev

在设置页面中切换至新添加的语言，检查以下项目：

所有页面标题和标签是否正确显示
图表和列表中的空状态文本是否翻译
模态框和对话框按钮文本
系统托盘右键菜单（重启应用后生效）
日期和时间格式是否符合当地习惯

翻译最佳实践

保持术语一致：同一术语在整个应用中应使用相同翻译。
注意占位符：某些值包含插值如 {{count}}、{{appName}}，翻译时保留占位符。
考虑长度：UI 空间有限，避免过长的翻译导致截断。
使用正式/非正式语体：根据目标用户群体选择适当的语气。
测试复数规则：i18next 支持复数形式，确保 _plural 键被正确翻译。

提交你的翻译

如果你希望将新语言贡献给官方仓库：

Fork 仓库并创建新分支：git checkout -b feat/add-ja-language
完成上述所有步骤并测试通过
更新 README.md 中的语言支持列表
提交 PR，标题格式：feat(i18n): add Japanese (ja) language support

最后更新：2025-05-03 · TimeLens v1.1.0