Traduora 0.23 REST API 详解

一、概述

Traduora 提供完整的 RESTful API，基础路径 /api/v1/，所有端点均返回统一的 {"data": ...} 包装结构（未来计划加入分页元数据）。认证方式为 JWT Bearer Token，支持用户 password 和项目客户端 client_credentials 两种 grant type。

本指南以 0.23.0 版本源码 api/src/controllers/*.controller.ts 为基准整理全部 API 端点，附 curl 示例。API 控制器共 17 个，覆盖认证、用户、项目、词条、翻译、导入导出、客户端、邀请、标签、统计等完整业务域。

1.1 基础 URL 与协议

http(s)://<your-traduora-host>:8080/api/v1/

官方强烈建议 HTTPS，因为 JWT Bearer Token 在 HTTP Header 中传递，裸 HTTP 可被窃听。

1.2 统一响应格式

{
  "data": {
    // 实际响应内容（单个对象、对象数组、或简单值）
  }
}

1.3 HTTP 状态码

状态码	含义
200 OK	请求成功
201 Created	资源创建成功
400 Bad Request	请求体参数校验失败
401 Unauthorized	未认证或 Token 失效
403 Forbidden	无权限（角色不足）
404 Not Found	资源不存在
429 Too Many Requests	触发限流（TR_AUTH_THROTTLE_LIMIT 等）

1.4 角色与权限

每项目每个 User 有独立角色，权限矩阵：

权限	Admin	Editor	Viewer
查看项目/词条/翻译	✓	✓	✓
新增/编辑翻译	✓	✓	—
删除翻译	✓	✓	—
导入翻译文件	✓	✓	—
导出翻译文件	✓	✓	✓
管理词条 CRUD	✓	✓	—
管理项目设置	✓	—	—
管理项目成员	✓	—	—
管理 API 客户端	✓	—	—
删除项目	✓	—	—

二、认证

2.1 获取 Token（password grant type）

用户邮箱 + 密码换取 JWT Token：

curl -X POST http://127.0.0.1:8080/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "password",
    "email": "local.admin@ever.co",
    "password": "q1w2e3r4"
  }'

响应：

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 86400
  }
}

2.2 获取 Token（client_credentials grant type）

项目 API 客户端用自身 ID + Secret 换取 Token（适合 CI/CD）：

curl -X POST http://127.0.0.1:8080/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

2.3 使用 Token

后续请求统一带 Authorization Header：

curl -H 'Authorization: Bearer eyJhbGciOi...' \
  http://127.0.0.1:8080/api/v1/users/me

2.4 其他认证端点

端点	方法	说明
`/api/v1/auth/providers`	GET	获取可用 OAuth Provider（Google 等）
`/api/v1/auth/signup`	POST	自注册新用户（需 `TR_SIGNUPS_ENABLED=true`）
`/api/v1/auth/signup-provider`	POST	通过 OAuth Provider 注册
`/api/v1/auth/forgot-password`	POST	发送密码重置邮件
`/api/v1/auth/reset-password`	POST	使用 token 重置密码
`/api/v1/auth/change-password`	POST	已登录用户修改密码
`/api/v1/auth/verify-email`	POST	验证邮箱
`/api/v1/auth/resend-verification-email`	POST	重发验证邮件
`/api/v1/auth/accept-invite`	POST	接受项目邀请

三、用户

3.1 获取当前用户

curl -H 'Authorization: Bearer <token>' \
  http://127.0.0.1:8080/api/v1/users/me

响应：

{
  "data": {
    "id": "abc123...",
    "email": "local.admin@ever.co",
    "name": "Admin",
    "createdAt": "2026-10-27T16:30:00.000Z",
    "updatedAt": "2026-10-27T16:30:00.000Z"
  }
}

3.2 更新 / 删除当前用户

端点	方法	说明
`/api/v1/users/me`	PATCH	更新名称/邮箱
`/api/v1/users/me`	DELETE	删除账号

四、项目

4.1 创建项目

curl -X POST http://127.0.0.1:8080/api/v1/projects \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Website",
    "description": "Company main website localization"
  }'

响应：

{
  "data": {
    "id": "proj123...",
    "name": "My Website",
    "description": "Company main website localization",
    "createdAt": "2026-10-27T16:35:00.000Z",
    "updatedAt": "2026-10-27T16:35:00.000Z"
  }
}

4.2 项目端点一览

端点	方法	权限	说明
`/api/v1/projects`	GET	已认证	列出当前用户所有项目
`/api/v1/projects`	POST	已认证	创建项目
`/api/v1/projects/:projectId`	GET	项目成员	获取项目详情
`/api/v1/projects/:projectId`	PATCH	Admin	更新项目
`/api/v1/projects/:projectId`	DELETE	Admin	删除项目
`/api/v1/projects/:projectId/plan`	GET	项目成员	获取项目套餐信息
`/api/v1/projects/:projectId/stats`	GET	项目成员	获取统计（词条数、翻译数）

五、词条（Term）

词条是翻译的键名，类似 i18next 中的 key 或 gettext 中的 msgid。

5.1 创建词条

curl -X POST http://127.0.0.1:8080/api/v1/projects/:projectId/terms \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "homepage.title",
    "description": "Displayed on browser tab",
    "labels": ["web"]
  }'

5.2 词条端点

端点	方法	权限	说明
`/api/v1/projects/:projectId/terms`	GET	项目成员	列出词条（分页）
`/api/v1/projects/:projectId/terms/filter-by-label`	GET	项目成员	按 label 筛选
`/api/v1/projects/:projectId/terms`	POST	Admin/Editor	创建词条
`/api/v1/projects/:projectId/terms/:termId`	PATCH	Admin/Editor	更新词条
`/api/v1/projects/:projectId/terms/:termId`	DELETE	Admin/Editor	删除词条

六、翻译（Translation）

每个词条可对应多个 locale（语言-地区组合）的翻译值。

6.1 创建翻译

curl -X POST http://127.0.0.1:8080/api/v1/projects/:projectId/translations \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "termId": "term123...",
    "localeCode": "en_US",
    "value": "Welcome to our website"
  }'

6.2 翻译端点

端点	方法	权限	说明
`/api/v1/projects/:projectId/translations`	GET	项目成员	列出所有翻译
`/api/v1/projects/:projectId/translations/:localeCode`	GET	项目成员	列出指定 locale 的翻译
`/api/v1/projects/:projectId/translations`	POST	Admin/Editor	创建翻译
`/api/v1/projects/:projectId/translations/:localeCode`	PATCH	Admin/Editor	批量更新指定 locale 的翻译
`/api/v1/projects/:projectId/translations/:localeCode`	DELETE	Admin/Editor	删除指定 locale 的全部翻译

6.3 locale 端点

# 列出系统支持的所有 locale
curl http://127.0.0.1:8080/api/v1/locales

响应：

{
  "data": [
    {"code": "en_US", "language": "English", "region": "United States"},
    {"code": "zh_CN", "language": "Chinese", "region": "China"},
    {"code": "ja_JP", "language": "Japanese", "region": "Japan"}
  ]
}

七、批量导入

7.1 支持的导入格式

POST /api/v1/projects/:projectId/imports 支持以下 file 类型（multipart/form-data）：

格式	Content-Type	文件扩展名	说明
JSON（flat）	`application/json`	`.json`	`{"key": "value"}`
JSON（nested）	`application/json`	`.json`	`{"group": {"key": "value"}}`
YAML（flat）	`text/yaml`	`.yaml` / `.yml`	`key: value`
YAML（nested）	`text/yaml`	`.yaml` / `.yml`	`group:\n key: value`
Java Properties	`text/plain`	`.properties`	`key=value`
CSV	`text/csv`	`.csv`	首列 key、第二列 value
Gettext	`text/plain`	`.po`	标准 PO 文件
XLIFF 1.2	`application/xml`	`.xlf` / `.xliff`	XML 翻译交换格式
Apple Strings	`text/plain`	`.strings`	`"key" = "value";`
Android Resources	`application/xml`	`.xml`	`<string name="key">value</string>`
PHP Arrays	`text/plain`	`.php`	`return [...]`

7.2 导入请求示例

curl -X POST http://127.0.0.1:8080/api/v1/projects/:projectId/imports \
  -H 'Authorization: Bearer <token>' \
  -F 'file=@./translations/en_US.json;type=application/json' \
  -F 'localeCode=en_US' \
  -F 'format=json'

7.3 导入参数说明

参数	类型	必填	说明
`file`	file	是	翻译文件内容（multipart/form-data）
`localeCode`	string	是	目标语言代码，如 `en_US`
`format`	string	是	格式标识：`json` / `yaml` / `properties` / `csv` / `po` / `xliff` / `strings` / `android-xml` / `php`

导入成功返回异步作业 ID，可通过 GET exports/imports 端点查询进度。

八、批量导出

8.1 导出端点

curl -X GET 'http://127.0.0.1:8080/api/v1/projects/:projectId/exports' \
  -H 'Authorization: Bearer <token>' \
  -o ./exported_translations.json \
  -G \
  --data-urlencode 'format=json' \
  --data-urlencode 'localeCodes=en_US,zh_CN'

8.2 导出参数

参数	类型	必填	说明
`format`	string	是	同导入支持的 11 种格式标识
`localeCodes`	string	是	逗号分隔的 locale 代码列表
`labelId`	string	否	只导出指定 label 下的词条
`termId`	string	否	只导出单个词条

九、项目 API 客户端（CI/CD 集成）

9.1 创建客户端

项目 Admin 可创建 API Client，获得 client_id + client_secret，用于 client_credentials grant：

curl -X POST http://127.0.0.1:8080/api/v1/projects/:projectId/clients \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "CI Build Pipeline",
    "description": "Used by GitHub Actions to sync translations"
  }'

响应：

{
  "data": {
    "id": "client123...",
    "name": "CI Build Pipeline",
    "secret": "super-secret-client-secret-here",  // 仅返回一次，需保存！
    "revoked": false
  }
}

9.2 客户端端点

端点	方法	权限	说明
`/api/v1/projects/:projectId/clients`	GET	Admin	列出项目所有客户端
`/api/v1/projects/:projectId/clients`	POST	Admin	创建客户端（注意：secret 仅返回一次）
`/api/v1/projects/:projectId/clients/:clientId`	PATCH	Admin	更新名称/描述
`/api/v1/projects/:projectId/clients/:clientId`	DELETE	Admin	撤销（revoke）客户端
`/api/v1/projects/:projectId/clients/:clientId/rotate-secret`	POST	Admin	轮换 secret

9.3 CI/CD 集成示例（GitHub Actions）

- name: Sync translations from Traduora
  run: |
    # 1. 获取 token
    TOKEN=$(curl -s -X POST ${{ secrets.TRADUORA_API_URL }}/api/v1/auth/token \
      -H 'Content-Type: application/json' \
      -d "{
        \"grant_type\": \"client_credentials\",
        \"client_id\": \"${{ secrets.TRADUORA_CLIENT_ID }}\",
        \"client_secret\": \"${{ secrets.TRADUORA_CLIENT_SECRET }}\"
      }" | jq -r '.data.access_token')

    # 2. 导出 en_US 和 zh_CN
    curl -X GET "${{ secrets.TRADUORA_API_URL }}/api/v1/projects/${{ secrets.TRADUORA_PROJECT_ID }}/exports?format=json&localeCodes=en_US,zh_CN" \
      -H "Authorization: Bearer $TOKEN" \
      -o ./src/i18n/translations.zip

    # 3. 导入更新（反向同步）
    curl -X POST "${{ secrets.TRADUORA_API_URL }}/api/v1/projects/${{ secrets.TRADUORA_PROJECT_ID }}/imports" \
      -H "Authorization: Bearer $TOKEN" \
      -F 'file=@./src/i18n/translations/en_US.json;type=application/json' \
      -F 'localeCode=en_US' \
      -F 'format=json'

十、其他端点

10.1 项目成员管理

端点	方法	权限	说明
`/api/v1/projects/:projectId/users`	GET	项目成员	列出项目所有用户
`/api/v1/projects/:projectId/users/:userId`	PATCH	Admin	更新用户角色
`/api/v1/projects/:projectId/users/:userId`	DELETE	Admin	移除用户

10.2 邀请

端点	方法	权限	说明
`/api/v1/projects/:projectId/invites`	GET	Admin	列出邀请
`/api/v1/projects/:projectId/invites`	POST	Admin	创建邀请链接
`/api/v1/projects/:projectId/invites/:inviteId`	PATCH	Admin	更新邀请
`/api/v1/projects/:projectId/invites/:inviteId`	DELETE	Admin	撤销邀请

10.3 Label（标签）

Label 用于给词条/翻译分组（例如 web、mobile、v2-migration）：

端点	方法	权限	说明
`/api/v1/projects/:projectId/labels`	GET	项目成员	列出标签
`/api/v1/projects/:projectId/labels`	POST	Admin/Editor	创建标签
`/api/v1/projects/:projectId/labels/:labelId`	PATCH	Admin/Editor	更新
`/api/v1/projects/:projectId/labels/:labelId`	DELETE	Admin/Editor	删除
`/api/v1/projects/:projectId/labels/:labelId/terms/:termId`	POST	Admin/Editor	关联词条
`/api/v1/projects/:projectId/labels/:labelId/terms/:termId`	DELETE	Admin/Editor	取消关联词条

10.4 健康检查

curl http://127.0.0.1:8080/health

响应：

{"status":"ok","timestamp":"2026-10-27T16:40:00.000Z"}

十一、完整 API 端点树

以下是 0.23.0 版本源码 api/src/controllers/ 下 17 个 controller 提取的全部端点：

/api/v1/
├── auth
│   ├── GET    /providers
│   ├── POST   /signup
│   ├── POST   /signup-provider
│   ├── POST   /token
│   ├── POST   /forgot-password
│   ├── POST   /reset-password
│   ├── POST   /change-password
│   ├── POST   /verify-email
│   ├── POST   /resend-verification-email
│   └── POST   /accept-invite
├── users
│   ├── GET    /me
│   ├── PATCH  /me
│   └── DELETE /me
├── locales
│   └── GET    /
└── projects
    ├── GET    /
    ├── POST   /
    ├── GET    /:projectId
    ├── PATCH  /:projectId
    ├── DELETE /:projectId
    ├── GET    /:projectId/plan
    ├── GET    /:projectId/stats
    ├── GET    /:projectId/users
    ├── PATCH  /:projectId/users/:userId
    ├── DELETE /:projectId/users/:userId
    ├── GET    /:projectId/clients
    ├── POST   /:projectId/clients
    ├── PATCH  /:projectId/clients/:clientId
    ├── POST   /:projectId/clients/:clientId/rotate-secret
    ├── DELETE /:projectId/clients/:clientId
    ├── GET    /:projectId/invites
    ├── POST   /:projectId/invites
    ├── PATCH  /:projectId/invites/:inviteId
    ├── DELETE /:projectId/invites/:inviteId
    ├── GET    /:projectId/terms
    ├── GET    /:projectId/terms/filter-by-label
    ├── POST   /:projectId/terms
    ├── PATCH  /:projectId/terms/:termId
    ├── DELETE /:projectId/terms/:termId
    ├── GET    /:projectId/translations
    ├── POST   /:projectId/translations
    ├── GET    /:projectId/translations/:localeCode
    ├── PATCH  /:projectId/translations/:localeCode
    ├── DELETE /:projectId/translations/:localeCode
    ├── POST   /:projectId/imports
    ├── GET    /:projectId/exports
    ├── GET    /:projectId/labels
    ├── POST   /:projectId/labels
    ├── PATCH  /:projectId/labels/:labelId
    ├── DELETE /:projectId/labels/:labelId
    ├── POST   /:projectId/labels/:labelId/terms/:termId
    ├── DELETE /:projectId/labels/:labelId/terms/:termId
    ├── POST   /:projectId/labels/:labelId/terms/:termId/translations/:localeCode
    └── DELETE /:projectId/labels/:labelId/terms/:termId/translations/:localeCode

/health  (不在 /api/v1/ 下，根路径)

十二、实战流程示例

以下是从零到能在 CI/CD 中使用 Traduora 的完整 API 流程。

12.1 Step 1：用户获取 Token

export TOKEN=$(curl -s -X POST http://127.0.0.1:8080/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"password","email":"local.admin@ever.co","password":"q1w2e3r4"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['access_token'])")

12.2 Step 2：创建项目

export PROJ_ID=$(curl -s -X POST http://127.0.0.1:8080/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"MyWebApp","description":"Frontend localization"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['id'])")
echo "Project ID: $PROJ_ID"

12.3 Step 3：批量导入英文词条（JSON flat）

cat > /tmp/en_translations.json << 'EOF'
{
  "app.title": "My Web App",
  "app.description": "A really cool web application",
  "nav.home": "Home",
  "nav.settings": "Settings"
}
EOF

curl -s -X POST "http://127.0.0.1:8080/api/v1/projects/$PROJ_ID/imports" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'file=@/tmp/en_translations.json;type=application/json' \
  -F 'localeCode=en_US' \
  -F 'format=json'

12.4 Step 4：批量导入中文翻译

cat > /tmp/zh_translations.json << 'EOF'
{
  "app.title": "我的 Web 应用",
  "app.description": "一款非常酷的 web 应用",
  "nav.home": "首页",
  "nav.settings": "设置"
}
EOF

curl -s -X POST "http://127.0.0.1:8080/api/v1/projects/$PROJ_ID/imports" \
  -H "Authorization: Bearer $TOKEN" \
  -F 'file=@/tmp/zh_translations.json;type=application/json' \
  -F 'localeCode=zh_CN' \
  -F 'format=json'

12.5 Step 5：创建 API 客户端（供 CI 使用）

export CLIENT_ID=$(curl -s -X POST "http://127.0.0.1:8080/api/v1/projects/$PROJ_ID/clients" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"GitHub Actions","description":"Auto-sync translations"}' \
  | python3 -c "import sys,json; d=json.load(sys.stdin)['data']; print(d['id']); print('SECRET:', d['secret'])")

⚠️ Client Secret 仅返回一次！请立即保存到 CI 系统的 Secret Manager（GitHub Secrets / GitLab CI Variables / 环境变量等）。

12.6 Step 6：CI 环境用 client_credentials 拉取翻译

export CI_TOKEN=$(curl -s -X POST http://127.0.0.1:8080/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\"}" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['access_token'])")

# 导出 JSON flat 格式，en_US + zh_CN
curl -s -X GET "http://127.0.0.1:8080/api/v1/projects/$PROJ_ID/exports?format=json&localeCodes=en_US,zh_CN" \
  -H "Authorization: Bearer $CI_TOKEN" \
  -o ./src/i18n/translations.json

echo "✅ 翻译同步完成"

十三、与同类方案对比

维度	Traduora API	Tolgee API	Weblate API
基础路径	`/api/v1/`	`/v1/`	`/api/`
认证方式	JWT Bearer（password + client_credentials）	JWT + API Key	Token 认证
导入格式	11 种	14 种	40+ 种
导出格式	11 种	14 种	40+ 种
API 客户端管理	项目级 client_id + client_secret	个人 API Key	全局 Token
CI/CD 友好度	⭐⭐⭐⭐⭐（项目级 credentials 天然适合）	⭐⭐⭐⭐	⭐⭐⭐
Swagger	源码 controller decorators（可自行生成）	内置 Swagger UI	内置 Swagger

十四、社区工具

非官方 CLI：github.com/iilei/traduora-cli（Go 实现，支持 pull/push 翻译文件，可在 CI 中直接用）
Rust bindings：docs.rs/traduora（社区维护，覆盖主要端点）
Swagger UI：官方计划提供，当前可基于 NestJS controller decorators（@Get / @Post）自动生成

十五、安全注意事项

Token 有效期：默认 24 小时（TR_AUTH_TOKEN_EXPIRES=86400），CI 环境需注意刷新
HTTPS 必开：JWT Bearer Token 在 HTTP Header 中传递，裸 HTTP 可被中间人窃听
Client Secret 仅返回一次：务必立即保存；丢失需要 rotate
限流保护：TR_AUTH_THROTTLE_LIMIT 默认认证接口 10/min（dev）/100/min（prod），防暴力破解
登录失败锁定：连续 3 次失败后锁 15 分钟（TR_LOGIN_ATTEMPTS_MAX=3 / TR_LOGIN_ATTEMPTS_TTL=900000）
修改 TR_SECRET 会使所有 Token 失效：用户需重新登录，API Client 需重新认证
无公开默认密钥：0.23.0 起强制校验，拒绝 secret / supersecretkey / mysupersecret 等

十六、延伸阅读

《Traduora 介绍与选型指南》：技术栈与架构
《Traduora 0.23 配置参数详解》：TR_* 环境变量逐项说明
《Traduora 0.23 Docker Compose 部署指南》：快速起环境实测 API
《Ubuntu 22.04 安装 Traduora 0.23 指南》：裸机 systemd 安装

十七、信息来源

来源	路径	查询日期
API controller 源码	`api/src/controllers/*.controller.ts`	2026-10-27
源码（clone 自 develop 分支）	ever-co/ever-traduora	2026-10-27
官方 API 概览	https://docs.traduora.co/api/v1/overview/	2026-10-27
官方认证文档	https://docs.traduora.co/api/v1/authentication/	2026-10-27
官方角色权限	https://docs.traduora.co/api/v1/roles-permissions/	2026-10-27
package.json	version: 0.23.0	2026-10-27