|
| 1 | +--- |
| 2 | +name: manage-translations |
| 3 | +description: "指导如何在 Project Graph 项目中管理多语言翻译。当需要添加新翻译、更新现有翻译或了解翻译系统结构时使用此技能。" |
| 4 | +--- |
| 5 | + |
| 6 | +# 管理翻译 |
| 7 | + |
| 8 | +本技能指导如何在 Project Graph 项目中管理多语言翻译。 |
| 9 | + |
| 10 | +## 翻译文件位置 |
| 11 | + |
| 12 | +所有翻译文件位于 `app/src/locales/` 目录下： |
| 13 | + |
| 14 | +``` |
| 15 | +app/src/locales/ |
| 16 | +├── en.yml # 英文 |
| 17 | +├── id.yml # 印度尼西亚语 |
| 18 | +├── zh_CN.yml # 简体中文 |
| 19 | +├── zh_TW.yml # 繁体中文 |
| 20 | +├── zh_TWC.yml # 接地气繁体中文 |
| 21 | +└── README.md # 翻译系统说明 |
| 22 | +``` |
| 23 | + |
| 24 | +## 查看当前支持的语言 |
| 25 | + |
| 26 | +在添加或修改翻译前，先查看 `app/src/locales/` 目录下有哪些 `.yml` 文件： |
| 27 | + |
| 28 | +```bash |
| 29 | +ls app/src/locales/*.yml |
| 30 | +``` |
| 31 | + |
| 32 | +## 添加新翻译 |
| 33 | + |
| 34 | +### 1. 确定翻译键名 |
| 35 | + |
| 36 | +翻译使用层级结构，通常按功能模块组织： |
| 37 | + |
| 38 | +```yaml |
| 39 | +# 基本结构 |
| 40 | +moduleName: |
| 41 | + featureName: |
| 42 | + title: "标题文本" |
| 43 | + description: "描述文本" |
| 44 | +``` |
| 45 | +
|
| 46 | +### 2. 在所有语言文件中添加 |
| 47 | +
|
| 48 | +为每个 `.yml` 文件添加对应的翻译。例如添加一个设置项的翻译： |
| 49 | + |
| 50 | +**zh_CN.yml:** |
| 51 | + |
| 52 | +```yaml |
| 53 | +settings: |
| 54 | + enableNewFeature: |
| 55 | + title: "启用新功能" |
| 56 | + description: "开启后将启用新功能特性" |
| 57 | + options: |
| 58 | + option1: "选项一" |
| 59 | + option2: "选项二" |
| 60 | +``` |
| 61 | + |
| 62 | +**en.yml:** |
| 63 | + |
| 64 | +```yaml |
| 65 | +settings: |
| 66 | + enableNewFeature: |
| 67 | + title: "Enable New Feature" |
| 68 | + description: "Enable to activate the new feature" |
| 69 | + options: |
| 70 | + option1: "Option 1" |
| 71 | + option2: "Option 2" |
| 72 | +``` |
| 73 | + |
| 74 | +**其他语言文件同理...** |
| 75 | + |
| 76 | +### 3. 翻译内容规范 |
| 77 | + |
| 78 | +- **title**: 简短标题，3-10个字 |
| 79 | +- **description**: 详细描述，可以包含多行（使用 `|`） |
| 80 | +- **options**: 仅枚举类型需要，列出所有选项的显示文本 |
| 81 | + |
| 82 | +## 翻译使用方式 |
| 83 | + |
| 84 | +### 在代码中使用 |
| 85 | + |
| 86 | +```typescript |
| 87 | +import i18next from "i18next"; |
| 88 | +
|
| 89 | +// 简单翻译 |
| 90 | +const title = i18next.t("settings.enableNewFeature.title"); |
| 91 | +
|
| 92 | +// 带参数的翻译 |
| 93 | +const message = i18next.t("common.deleted", { count: 5 }); |
| 94 | +
|
| 95 | +// 指定命名空间（如 keyBinds） |
| 96 | +const keyBindTitle = i18next.t("saveFile.title", { ns: "keyBinds", defaultValue: "" }); |
| 97 | +``` |
| 98 | + |
| 99 | +### 在 React 组件中使用 |
| 100 | + |
| 101 | +```tsx |
| 102 | +import { useTranslation } from "react-i18next"; |
| 103 | +
|
| 104 | +function MyComponent() { |
| 105 | + const { t } = useTranslation(); |
| 106 | +
|
| 107 | + return <div>{t("settings.enableNewFeature.title")}</div>; |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | +## 添加新语言 |
| 112 | + |
| 113 | +1. 在 `app/src/locales/` 目录下创建新的 `.yml` 文件 |
| 114 | +2. 复制现有语言文件（如 `en.yml`）作为模板 |
| 115 | +3. 将所有值翻译为目标语言 |
| 116 | +4. 在语言配置中添加新语言（如有语言选择功能） |
| 117 | + |
| 118 | +## 注意事项 |
| 119 | + |
| 120 | +1. **保持键名一致**: 所有语言文件中的键名必须完全一致 |
| 121 | +2. **不要遗漏**: 添加新翻译时，确保为所有语言文件都添加 |
| 122 | +3. **使用英文作为后备**: 如果某个翻译缺失，系统会回退到英文 |
| 123 | +4. **参数占位符**: 使用 `{{paramName}}` 语法添加可变参数 |
| 124 | +5. **多行文本**: 使用 `|` 符号表示多行文本 |
0 commit comments