从"翻译错误"到"发生错误"：Read Frog中文显示问题深度修复指南

从"翻译错误"到"发生错误"：Read Frog中文显示问题深度修复指南

问题现象与影响范围

当用户在使用Read Frog(陪读蛙)浏览器插件进行网页翻译时，部分错误提示仍显示为英文，如"Translation Error"和"Something went wrong"，与界面其他中文元素形成明显反差。这种本地化不完整问题严重影响用户体验，尤其对英语水平有限的用户造成理解障碍。通过对错误场景的复现分析，发现问题主要集中在翻译失败时的错误提示组件，涉及两个关键硬编码字符串。

问题根源定位

1. 本地化文件结构分析

通过检查项目本地化资源文件(apps/extension/src/locales/zh-CN.yml)，发现翻译模块(translation)下缺少错误提示相关的键值对定义：

# 原文件缺失部分
translation:
  sameLanguage: 源语言和目标语言必须不同
  autoModeSameLanguage: 检测到的语言 '$1' 与目标语言相同
  # 缺少error子节点定义

2. 代码实现问题

在翻译错误处理组件(translation/error/error-button.tsx)中，错误标题和默认消息直接使用英文硬编码，未通过本地化函数t()获取翻译文本：

// 问题代码片段
<AlertTitle>Translation Error</AlertTitle>
<AlertDescription className="break-all">
  <p className="text-zinc-900 dark:text-zinc-100">
    {error.message || 'Something went wrong'}
  </p>
</AlertDescription>

这种实现方式违反了项目的i18n规范，导致即使在中文环境下也无法显示正确翻译。

解决方案设计

修复策略

采用"双管齐下"的修复方案：

1. 代码层面：将硬编码字符串替换为本地化函数调用
2. 资源层面：在中文本地化文件中添加对应翻译条目

实施步骤

步骤1：修改错误提示组件

使用项目标准的本地化函数t()重构错误提示文本，确保从语言文件动态获取内容：

// apps/extension/src/components/translation/error/error-button.tsx
- <AlertTitle>Translation Error</AlertTitle>
+ <AlertTitle>{t("translation.error.title")}</AlertTitle>

- {error.message || 'Something went wrong'}
+ {error.message || t("translation.error.somethingWentWrong")}

步骤2：完善中文本地化文件

在zh-CN.yml的translation节点下添加错误提示专用条目：

// apps/extension/src/locales/zh-CN.yml
translation:
+  error:
+    title: 翻译错误
+    somethingWentWrong: 发生错误，请稍后重试
  sameLanguage: 源语言和目标语言必须不同
  autoModeSameLanguage: 检测到的语言 '$1' 与目标语言相同

步骤3：验证修复效果

1. 构建并加载修改后的插件
2. 故意触发翻译错误(如使用无效API Key)
3. 确认错误提示已正确显示为中文：
   • 标题显示"翻译错误"
   • 默认错误消息显示"发生错误，请稍后重试"

关键技术点解析

本地化实现机制

Read Frog采用基于YAML文件的i18n方案，通过键值对组织不同语言的文本资源：

# 本地化键值对结构
模块名:
  子模块名:
    键名: 翻译文本

在代码中通过t()函数按路径访问：t("模块名.子模块名.键名")

错误处理流程

翻译错误处理组件的工作流程：

预防类似问题的措施

1. 代码审查规范

• 强制所有UI文本必须使用t()函数
• 新增字符串必须同时提供中英文翻译
• 使用ESLint规则检测硬编码字符串：

// eslint规则示例
rules: {
  "no-hardcoded-strings": ["error", {
    "ignore": ["^[a-zA-Z0-9_\\-]+$"] // 允许标识符
  }]
}

2. 自动化测试

添加本地化完整性测试，确保所有键在各语言文件中都有对应值：

// 本地化测试示例
test('所有中文翻译键都有对应英文翻译', () => {
  const enKeys = getTranslationKeys('en.yml');
  const zhKeys = getTranslationKeys('zh-CN.yml');
  
  expect(zhKeys).toEqual(expect.arrayContaining(enKeys));
});

总结与展望

本次修复不仅解决了特定的中文显示问题，更完善了项目的本地化框架。通过建立"代码-资源"联动的i18n机制，为后续支持更多语言(如日语、韩语)奠定基础。未来计划实现：

1. 本地化覆盖率统计工具
2. 社区翻译贡献平台
3. 动态语言切换功能

这些改进将使Read Frog真正成为全球化的语言学习工具，帮助更多用户突破语言障碍，自由获取信息。