内容
<p align="center">
<img src="assets/turjuman-mark.svg" alt="Turjuman" width="96" height="96" />
</p>
# Turjuman
**开源、自托管的翻译管理 — 由您的 AI 代理管理。**
Turjuman 是一个轻量级、开源的商业翻译管理 SaaS 替代方案。您可以通过与 Claude Code（或任何 MCP 客户端/代理）连接的 **MCP 服务器** 管理项目、密钥、本地化和翻译。
一个薄 **开发者 CLI** 处理确定性文件工作 — 在您的存储库和 CI 中拉取/推送本地文件。
它运行在 **无服务器 AWS 堆栈（Lambda + DynamoDB）** 上，托管成本几乎为零，并舒适地适应免费层。无需始终在线的服务器，也无需 Cognito。
```
Claude Code / 代理 ──流式 HTTP + API 密钥──┐
开发者 CLI / CI ──REST + API 密钥──────────────┤
▼
Lambda 函数 URL ──► DynamoDB（单表）
```
## 为什么优先使用 MCP？
翻译管理主要是对话 + 判断：“添加法语本地化”，“翻译未翻译的结账字符串”，“`cart.empty` 在德语中怎么说？”。具有正确工具的代理自然可以做到这一点。连接的 LLM **直接进行翻译** — 无需支付或配置单独的机器翻译引擎。
CLI 适用于您不应该交给 LLM 的事情：确定性导出 JSON/YAML 文件、下载翻译并在 CI 中同步它们。
## 功能（v1）
- **MCP 服务器**，包含 36 种工具：项目、本地化、密钥（带有描述/上下文）、翻译、批量填充、审查工作流和完整的用户/成员/API 密钥管理（包括密钥吊销）。
- **一流的 RBAC.** 全局角色（`OWNER`/`ADMIN`/`MEMBER`）+ 项目角色（`MANAGER`/`EDITOR`/`DEVELOPER`/`VIEWER`）。高权限用户管理其他用户的所有访问权限。
- **词汇表 + 翻译记忆**，以及 **webhooks** （HMAC 签名，通过 DynamoDB 流）用于更改事件。
- **API 密钥身份验证** — 简单的承载令牌，存储为哈希值。（OAuth/Cognito 是未来选项。）
- **开发者 CLI** — `login`、`init`、`pull`、`push`、`build`，具有多目标配置和适配器，用于 JSON（嵌套/扁平）、YAML、Flutter ARB、Java `.properties`、CSV、Android `strings.xml` 和 iOS `.strings`/`.stringsdict`（ICU 标准复数转换为每种格式的原生形式）。
- **DynamoDB 单表设计**，按需计费。支持多租户（`orgId` 在每个记录上）。
## 仓库布局
| 软件包 | 它是什么 |
|---|---|
| `packages/core` | 领域模型、DynamoDB 存储库、RBAC、服务、格式适配器（共享大脑） |
| `packages/mcp-server` | 无状态流式 HTTP MCP 服务器 → Lambda |
| `packages/api` | CLI/CI 的 REST API → Lambda，以及 webhook 分发器 |
| `packages/cli` | `turjuman` 开发者 CLI（本地文件同步 + 首位所有者 `bootstrap`） |
## 在本地试用
体验 Turjuman 的最快方式 — 所有操作都在本地 [LocalStack](https://www.localstack.cloud/) 上运行（需要 Docker + Node 24+），无需云账户。
Turjuman 使用 [pnpm](https://pnpm.io) （通过 `package.json` 的 `packageManager` 字段固定）；运行 `corepack enable` 即可激活它。
```bash
pnpm install && pnpm run build
pnpm run localstack:up # 启动共享的 LocalStack，监听 :4566
cp .env.example .env # 将工具链指向 LocalStack
# 部署到 LocalStack，热重载；打印 MCP/REST URL 和新的 API 密钥
pnpm run dev
```
`pnpm run dev` 在 LocalStack 中运行真正的 Lambda 运行时（因此 DynamoDB 流 → webhook 生效），并热重载您的编辑。 将您的 MCP 客户端指向打印的 MCP URL 和打印的 API 密钥，然后开始与它交互。
## 在 AWS 上自托管
> **状态：** CDK 堆栈是常规的，但 **尚未针对实时 AWS 账户进行端到端验证** （参见 [ROADMAP](ROADMAP.md)）。使用上述本地路径进行评估；将云部署视为测试版，请报告问题。
### 1. 部署到您的 AWS 账户
在小型 CDK 应用程序中实例化 `TurjumanStack`，并使用 AWS CDK CLI 部署它。该构造提供其 Lambda 包，因此无需 SAM CLI 和存储库克隆（有关完整的操作指南和配置，请参见 [自托管](docs/self-hosting.mdx)）：
```bash
npm install @turjuman/aws-cdk aws-cdk-lib constructs
cdk bootstrap # 每个账户 + 区域一次（标准 CDK 引导）
cdk deploy # 打印 McpUrl / ApiUrl / TableName 作为堆栈输出
```
`@turjuman/aws-cdk` 可独立安装，因此日常 `turjuman` 开发者 CLI 仍然是精简的、无需 AWS 的安装。
### 2. 您的第一个所有者和 API 密钥
堆栈启动后，通过 HTTP 创建第一个所有者并捕获其密钥 — **打印一次**，并保存到 `~/.turjuman/auth.json`，因此您已登录：
```bash
turjuman bootstrap --url <ApiUrl> --email you@example.com --name "您的姓名"
```
它拒绝在部署有用户后创建第二个所有者（返回 `409`），因此可以安全地重新运行。
### 3. 连接 Claude Code（MCP）
将以下内容添加到您的 `.mcp.json`（参见 `.mcp.json.example`）：
```json
{
"mcpServers": {
"turjuman": {
"type": "http",
"url": "<McpUrl>",
"headers": { "Authorization": "Bearer <your-api-key>" }
}
}
}
```
> **将您的密钥保密。** `.mcp.json` 通常被提交 — 优先通过环境变量/秘密管理器引用令牌，而不是粘贴文字密钥。如果密钥泄露，请立即吊销。
然后直接提问：*“创建一个名为 Web App 的项目，基准本地化为 en，添加 fr 和 es，并将所有内容翻译成法语。”*
### 4. 同步存储库中的文件（CLI）
```bash
pnpm dlx turjuman login --url <ApiUrl> --key <your-api-key>
pnpm dlx turjuman init --project <proj_id> --format json-nested --path "locales/{locale}.json"
pnpm dlx turjuman pull # 从 Turjuman 写入本地文件
pnpm dlx turjuman push # 上传源密钥/翻译
```
## 文档
完整文档位于 [`docs/`](docs/)，并作为文档站点发布，带有 [Mintlify](https://mintlify.com) — 一个为人类读者、外部代理（Mintlify 自动生成 `llms.txt` / `llms-full.txt` 和“在 Claude/ChatGPT 中打开”菜单）和在此存储库中工作的代理提供服务的单一源。 从这里开始：
- [介绍](docs/introduction.mdx) · [快速入门](docs/quickstart.mdx)（本地运行，无 AWS）· [自托管](docs/self-hosting.mdx)（在 AWS 上部署）
- [架构](docs/concepts/architecture.mdx) · [角色和权限](docs/concepts/roles-and-permissions.mdx) · [生命周期](docs/concepts/lifecycle.mdx)
- [使用 MCP 翻译](docs/guides/translate-with-mcp.mdx) · [使用 CLI 同步](docs/guides/sync-with-cli.mdx) · [质量检查](docs/guides/quality-checks.mdx) · [Webhooks](docs/guides/webhooks.mdx)
- 参考：[MCP 工具](docs/reference/mcp-tools.mdx) · [CLI 命令](docs/reference/cli-commands.mdx) · [文件格式](docs/reference/file-formats.mdx) · [QA 检查](docs/reference/qa-checks.mdx)
- [贡献](CONTRIBUTING.md) · [路线图](ROADMAP.md)
## 开发
```bash
pnpm install
pnpm run build
pnpm test # 单元测试（密封）
# 针对模拟的 AWS（LocalStack DynamoDB）的集成测试：
pnpm run localstack:up && pnpm run test:integration && pnpm run localstack:down
# 完整的部署端到端测试（SAM 堆栈在 LocalStack 上：Lambda 函数 URL + 真实的 DynamoDB 流 -> webhook 流）。仅需 Docker：
pnpm run test:e2e
```
### 格式化和 linting
格式化和 linting 由 [Biome](https://biomejs.dev) 处理（一种单一的、快速的 Rust 基准格式化工具，替代 Prettier + ESLint），在 `biome.json` 中配置：
```bash
pnpm run check # 格式化 + linting，仅报告
pnpm run check:write # 应用格式化 + 安全的 linting 修复
pnpm run format # 仅格式化
pnpm run lint # 仅 linting
```
您很少手动运行这些。 `pre-commit` 钩子自动格式化暂存文件，CI 运行 `biome ci .`，并且 — 由于此存储库主要使用 Claude Code 开发 — `PostToolUse` 钩子（`.claude/hooks/biome-format.sh`）在代理编辑每个文件时自动格式化。 生成的 `docs/api-reference/openapi.json` 快照由 `gen:openapi` 拥有，并从 Biome 中排除。
参见 [贡献](CONTRIBUTING.md) 以获取完整的测试指南（单元测试、LocalStack 集成测试和部署端到端测试），这些测试也在 CI 中运行。
## 许可证
MIT
