Skip to content

CHINESE_I18N_GUIDE.md

Latest commit

 

History

History
312 lines (234 loc) · 6.86 KB

CHINESE_I18N_GUIDE.md

File metadata and controls

312 lines (234 loc) · 6.86 KB

opcode 中文支持实现指南

本指南说明如何为 opcode 项目添加完整的中文支持。

已完成的工作

✅ 已安装的依赖

  • i18next
  • react-i18next
  • i18next-browser-languagedetector

✅ 已创建的文件

  1. src/i18n.ts - i18n 配置文件
  2. src/locales/en.json - 英文翻译文件
  3. src/locales/zh-CN.json - 中文翻译文件
  4. src/components/LanguageSwitcher.tsx - 语言切换组件

✅ 已更新的文件

  1. src/main.tsx - 已导入 i18n 配置

如何在组件中使用 i18n

基础用法

在任何组件中，按以下步骤使用翻译：

import { useTranslation } from 'react-i18next';

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

  return (
    <div>
      <h1>{t('projects.title')}</h1>
      <p>{t('projects.description')}</p>
      <button>{t('common.save')}</button>
    </div>
  );
};

带变量的翻译

对于包含动态值的文本：

// 翻译键：'projects.viewAll': 'View all ({{count}})'
<span>{t('projects.viewAll', { count: projects.length })}</span>

// 翻译键：'sessions.sessionOn': 'Session on {{date}}'
<h3>{t('sessions.sessionOn', { date: formattedDate })}</h3>

添加语言切换器

方法 1：在设置页面添加

找到 Settings.tsx 组件的 General 标签部分，在主题设置之后添加：

import { useTranslation } from 'react-i18next';
import { LanguageSwitcher } from './LanguageSwitcher';

// 在 Settings 组件的 General 标签中添加
<div className="space-y-4">
  {/* 现有的主题设置 */}

  {/* 添加语言设置 */}
  <div className="space-y-2">
    <Label>{t('settings.general.language.label')}</Label>
    <p className="text-sm text-muted-foreground">
      {t('settings.general.language.description')}
    </p>
    <LanguageSwitcher />
  </div>
</div>

方法 2：在标题栏添加（推荐）

在 CustomTitlebar.tsx 中添加语言切换按钮：

import { LanguageSwitcher } from './LanguageSwitcher';

// 在标题栏的右侧按钮区域添加
<div className="flex items-center gap-1">
  <LanguageSwitcher />
  {/* 其他按钮 */}
  <TooltipSimple content={t('titlebar.agents')}>
    <motion.button onClick={onAgentsClick}>
      <Bot className="h-4 w-4" />
    </motion.button>
  </TooltipSimple>
  {/* ... */}
</div>

更新现有组件的步骤

对于每个需要国际化的组件，按以下步骤操作：

1. 导入 useTranslation hook

import { useTranslation } from 'react-i18next';

2. 在组件中使用 hook

export const MyComponent = () => {
  const { t } = useTranslation();
  // ... 组件代码
}

3. 替换硬编码文本

替换前：

<h1>Projects</h1>
<p>Select a project to start working with Claude Code</p>
<button>Open Project</button>

替换后：

<h1>{t('projects.title')}</h1>
<p>{t('projects.description')}</p>
<button>{t('projects.openProject')}</button>

示例：更新 ProjectList 组件

import React, { useState } from 'react';
import { useTranslation } from 'react-i18next';
import { FolderCode } from 'lucide-react';
import { Card } from '@/components/ui/card';

export const ProjectList = ({ projects }) => {
  const { t } = useTranslation();
  const [showAll, setShowAll] = useState(false);

  if (!projects || projects.length === 0) {
    return (
      <div className="text-center py-12">
        <FolderCode className="h-12 w-12 mx-auto text-muted-foreground" />
        <h3 className="mt-4 text-lg font-semibold">
          {t('projects.noRecentTitle')}
        </h3>
        <p className="mt-2 text-sm text-muted-foreground">
          {t('projects.noRecentDescription')}
        </p>
        <button className="mt-4">
          {t('projects.openFirstProject')}
        </button>
      </div>
    );
  }

  return (
    <div>
      <h2 className="text-2xl font-bold">{t('projects.title')}</h2>
      <p className="text-muted-foreground">{t('projects.description')}</p>

      <div className="mt-6">
        <h3 className="text-lg font-semibold">{t('projects.recentProjects')}</h3>
        {/* 项目列表 */}
        <button onClick={() => setShowAll(!showAll)}>
          {showAll
            ? t('projects.viewLess')
            : t('projects.viewAll', { count: projects.length })
          }
        </button>
      </div>
    </div>
  );
};

测试中文支持

1. 手动切换语言

在浏览器控制台中运行：

// 切换到中文
window.i18n.changeLanguage('zh-CN')

// 切换到英文
window.i18n.changeLanguage('en')

2. 使用语言切换器

点击语言切换器组件，选择"简体中文"

3. 检查 localStorage

// 检查保存的语言设置
localStorage.getItem('i18nextLng')

优先更新的组件列表

建议按以下顺序更新组件（从用户最常见到的开始）：

  1. ✅ CustomTitlebar.tsx
  2. ⏳ ProjectList.tsx
  3. ⏳ SessionList.tsx
  4. ⏳ CCAgents.tsx
  5. ⏳ UsageDashboard.tsx
  6. ⏳ Settings.tsx
  7. ⏳ MCPManager.tsx
  8. ⏳ StartupIntro.tsx

添加新翻译

1. 更新翻译文件

在 src/locales/en.json 中添加新键：

{
  "myFeature": {
    "title": "My Feature",
    "description": "This is my new feature"
  }
}

在 src/locales/zh-CN.json 中添加对应的中文：

{
  "myFeature": {
    "title": "我的功能",
    "description": "这是我的新功能"
  }
}

2. 在组件中使用

const { t } = useTranslation();
// ...
<h1>{t('myFeature.title')}</h1>
<p>{t('myFeature.description')}</p>

常见问题

Q: 如何处理复数形式？

使用 i18next 的复数支持：

{
  "sessions": {
    "count_one": "{{count}} session",
    "count_other": "{{count}} sessions"
  }
}
t('sessions.count', { count: sessionCount })

Q: 如何在非组件中使用翻译？

import i18n from '@/i18n';

const message = i18n.t('common.error');

Q: 翻译不生效怎么办？

  1. 检查 i18n 是否在 main.tsx 中正确导入
  2. 确保翻译键在 JSON 文件中存在
  3. 检查浏览器控制台是否有错误
  4. 确保组件使用了 useTranslation hook

构建和运行

更新组件后，重新构建项目：

# 开发模式（推荐先测试）
cd opcode
bun run tauri dev

# 生产构建
cd opcode
bun run build
cargo build --release --manifest-path src-tauri/Cargo.toml

完成！

现在你的 opcode 应用已经支持中英文切换了！用户可以通过语言切换器在两种语言之间轻松切换，设置会自动保存在 localStorage 中。

作者注: 由于项目有84个组件文件，完全更新所有组件需要大量时间。本指南提供了完整的实现方法和示例，你可以根据需要逐步更新其他组件。最常用的组件（如标题栏、项目列表、设置页面）应该优先更新。