文档翻译

本项目使用 AWS Bedrock 的 Haiku 3.5 模型，将文档从英文自动翻译为多种语言。该翻译系统设计高效、准确且易于使用。

支持语言

目前支持以下语言：

日语 (jp)
法语 (fr)
西班牙语 (es)
德语 (de)
中文 (zh)
韩语 (ko)

工作原理

翻译系统通过以下步骤运作：

按 h2 标题拆分文档 - 实现更高效的上下文处理
保留 Markdown 格式 - 所有 Markdown 语法、代码块和 HTML 标签在翻译过程中保留
特殊处理 frontmatter - 翻译 YAML frontmatter 同时保持其结构
增量翻译 - 默认仅翻译变更文件，节省时间和资源

本地运行翻译

使用 scripts/translate.ts 脚本进行本地文档翻译：

# 默认仅翻译变更文件为日语
./scripts/translate.ts

# 翻译所有文件
./scripts/translate.ts --all

# 翻译指定语言
./scripts/translate.ts --languages jp,fr,es

# 预览翻译操作（不实际执行）
./scripts/translate.ts --dry-run

# 显示详细输出
./scripts/translate.ts --verbose

GitHub 工作流

当 Pull Request 中的英文文档发生变更时，GitHub 工作流会自动执行翻译。该工作流：

检测英文文档文件变更
使用 AWS Bedrock 翻译变更文件
将翻译结果提交回源分支
在 PR 中更新翻译状态

手动触发工作流

可通过 GitHub Actions 选项卡手动触发翻译工作流，适用于：

执行完整文档翻译
翻译指定语言
更新翻译脚本后的翻译刷新

AWS 配置

翻译系统使用 AWS Bedrock 的 Haiku 3.5 模型，需配置：

AWS 凭证 - 本地开发时通过 AWS CLI 或环境变量配置
IAM 角色 - GitHub Actions 需配置带 OIDC 认证和 AWS Bedrock 权限的 IAM 角色

必要权限

IAM 角色或用户需以下权限：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-3-haiku-20240307-v1:0"
      ]
    }
  ]
}

翻译质量

翻译质量整体较高，但需注意：

技术术语 - 系统配置保留英文技术术语
代码块 - 保持原始形式不翻译
上下文理解 - 翻译模型具备文档上下文理解能力

自定义翻译

通过修改 scripts/translate.ts 文件可自定义：

新增支持语言
更换翻译模型
调整翻译提示词
修改文档拆分处理方式

故障排除

遇到翻译问题时：

检查 AWS 凭证 - 确认凭证配置正确
检查 AWS 区域 - 确保使用支持 Bedrock 的区域
启用详细日志 - 使用 --verbose 参数
检查速率限制 - 大规模翻译需注意 AWS Bedrock 的速率限制