国际化

相关源文件

• frontend/__tests__/routes/settings.test.tsx
• frontend/src/components/shared/modals/settings/settings-form.tsx
• frontend/src/hooks/mutation/use-save-settings.ts
• frontend/src/hooks/query/use-settings.ts
• frontend/src/i18n/declaration.ts
• frontend/src/i18n/translation.json
• frontend/src/mocks/handlers.ts
• frontend/src/services/settings.ts
• frontend/src/types/settings.ts
• openhands/server/settings.py

本文档描述了 OpenHands 前端应用程序中使用的国际化 (i18n) 系统。它解释了翻译系统的结构、语言管理方式以及如何在应用程序中使用翻译。

概述

OpenHands 前端通过一个基于 react-i18next 构建的全面国际化系统支持多种语言。这使用户能够以他们偏好的语言与应用程序进行交互，从而增强了可访问性和用户体验。

该系统目前支持以下语言

• 英语 (en)
• 日语 (ja)
• 简体中文 (zh-CN)
• 繁体中文 (zh-TW)
• 韩语 (ko-KR)
• 挪威语 (no)
• 意大利语 (it)
• 葡萄牙语 (pt)
• 西班牙语 (es)
• 阿拉伯语 (ar)
• 法语 (fr)
• 土耳其语 (tr)
• 德语 (de)
• 波斯语/法西语 (fa) - 部分实现

来源: frontend/src/i18n/translation.json1-1023

系统架构

I18n 系统组件

来源: frontend/src/i18n/translation.json1-1023 frontend/src/i18n/declaration.ts1-420 frontend/src/routes/root-layout.tsx1-151

翻译工作流程

来源: frontend/src/routes/root-layout.tsx25-56

关键组件

翻译 JSON

所有翻译都存储在位于 frontend/src/i18n/translation.json 的结构化 JSON 文件中。该文件按翻译键组织，每个键包含所有支持语言的翻译。

翻译键遵循 SECTION$ELEMENT 格式的约定，以便按用法上下文组织字符串。

来源: frontend/src/i18n/translation.json77-91

I18n 键声明

为了确保类型安全并在引用翻译键时防止错误，系统使用 frontend/src/i18n/declaration.ts 中自动生成的枚举。

此枚举在应用程序中引用翻译键时被使用。

来源: frontend/src/i18n/declaration.ts1-10

语言管理

选择和切换语言

用户语言偏好存储在应用程序设置中。当用户更改其语言偏好时，应用程序会立即应用。

根布局组件中的此代码会监控语言设置的变化，并相应地更新 i18n 实例。

来源: frontend/src/routes/root-layout.tsx81-85 frontend/src/components/features/waitlist/auth-modal.tsx1-81

语言选择 UI

该应用程序在设置界面中提供语言选择器。这允许用户从支持的语言列表中选择他们偏好的语言。然后，所选语言将被存储在用户设置中并应用于应用程序。

来源: frontend/src/i18n/translation.json77-91

在组件中使用翻译

useTranslation Hook

组件使用 react-i18next 的 useTranslation Hook 来访问翻译。

此模式可确保对翻译字符串进行类型安全的访问，并在语言更改时自动更新渲染的内容。

来源: frontend/src/routes/root-layout.tsx25-56 frontend/src/components/features/waitlist/auth-modal.tsx1-81

认证和国际化

身份验证组件也使用国际化来在不同语言之间提供一致的用户体验。

来源: frontend/src/components/features/waitlist/auth-modal.tsx56-65

添加新内容

添加新的可翻译内容

要添加新的可翻译内容，请执行以下操作：

1. 在 frontend/src/i18n/translation.json 中添加一个新条目，其中包含所有支持语言的翻译。
2. declaration.ts 中的 I18nKey 枚举是根据翻译文件自动生成的。
3. 在组件中使用 useTranslation 的 t 函数来使用新键。

支持新语言

添加新语言支持

1. 对于 translation.json 中的每个条目，为新语言代码添加翻译。
2. 更新任何语言选择 UI 以包含新的语言选项。
3. 使用新语言测试 UI，以确保所有翻译都能正确显示。

实现细节

后端集成

国际化系统主要是前端的关注点，但语言偏好作为用户设置的一部分进行存储，这些设置可能会在后端持久化。

构建系统配置

前端构建系统 (Vite) 已配置为正确处理翻译文件。

来源: frontend/vite.config.ts9-75

最佳实践

1. 始终使用 I18nKey 枚举进行类型安全的翻译访问。
2. 使用 SECTION$ELEMENT 命名约定将翻译键按上下文进行组织。
3. 确保所有 UI 文本都是可翻译的，避免硬编码字符串。
4. 用不同的语言测试应用程序，以识别缺失的翻译或布局问题。

结论

OpenHands 中的国际化系统为多语言支持提供了坚实的基础。通过使用 react-i18next 等成熟的模式和库，应用程序可以根据用户偏好无缝地以多种语言呈现内容。

该系统设计得易于维护和扩展，允许在应用程序发展过程中轻松添加新的语言和可翻译内容。