Pi-hole Card多语言翻译指南：让全球用户畅享网络管理体验

项目背景与翻译意义

Pi-hole Card作为Home Assistant生态中的重要组件，为智能家居用户提供了直观的Pi-hole网络管理界面。通过多语言翻译，我们可以让全球不同地区的用户都能无障碍使用这一工具，真正实现智能家居的全球化体验。

当前支持语言现状

目前官方支持的语言包括：

• 英语（en） - 完整支持
• 西班牙语（es） - 完整支持
• 中文（zh-Hans） - 正在完善中

翻译工作完整流程

第一步：创建翻译文件

1. 复制基准文件：从src/translations/en.json复制作为模板
2. 规范命名：采用BCP 47标准语言代码命名
   • 法语：fr.json
   • 德语：de.json
   • 简体中文：zh-Hans.json
3. 内容翻译原则：
   • 保留左侧key值不变
   • 仅翻译右侧value内容
   • 保持JSON格式规范

示例对比（英语→法语）：

{
  "card": {
    "stats": {
      "total_queries": "Total queries",  // 英文原版
      "total_queries": "Requêtes totales"  // 法文翻译
    }
  }
}

第二步：集成到本地化系统

1. 在src/localize/localize.ts中导入新语言文件：

import * as zhHans from '../translations/zh-Hans.json';  // 新增中文翻译

2. 更新语言映射表：

const languages: Record<string, any> = {
  en: en,
  zhHans: zhHans  // 添加中文支持
};

第三步：类型定义更新（可选）

当新增翻译键值时，需要同步更新src/localize/types.ts中的类型定义，确保类型检查通过。

第四步：文档同步更新

1. 在项目文档中更新支持语言列表
2. 添加翻译者信息（如需要）

第五步：本地化测试

1. 在Home Assistant中切换测试语言
2. 检查所有UI元素的显示效果：
   • 文本是否完整显示
   • 特殊字符是否正常渲染
   • 布局是否因文本长度变化而错乱

专业翻译建议

1. 空间优化：卡片UI空间有限，中文翻译建议：

   • "Total queries" → "总查询"（优于"查询总数"）
   • "Active clients" → "活跃客户端"

2. 技术术语统一：

   • 保持DNS、Pi-hole等专业术语不翻译
   • 统一"query"的翻译（建议译为"查询"）

3. 动态参数处理：

   • 保留{number}等占位符
   • 确保语序兼容动态参数

4. 文化适应性：

   • 中文习惯使用主动语态
   • 避免直译造成的生硬表达

翻译质量控制

1. 母语优先：建议由目标语言母语者完成翻译
2. 上下文理解：理解每个字段的实际使用场景
3. 一致性检查：相同概念在不同位置保持相同译法
4. 视觉验证：实际部署测试显示效果

常见问题解决方案

1. 特殊字符显示异常：

   • 确保JSON文件使用UTF-8编码
   • 转义特殊字符

2. 文本溢出问题：

   • 优先缩写而非换行
   • 与开发团队协商调整布局

3. 动态参数位置问题：

   • 中文通常参数后置，如："已拦截{number}次"

翻译维护建议

1. 建立术语表保持一致性
2. 定期更新新增字段翻译
3. 收集用户反馈优化表达

通过规范的翻译流程和质量控制，我们可以让Pi-hole Card真正成为全球Home Assistant用户的得力助手，打破语言障碍，让网络管理变得更简单高效。