charx卡片翻译工作台

English | 中文

你是否在为其他卡片翻译器只翻译开场白，导致使用时面对界面上一堆异邦文字跟没翻译一样而感到烦躁？如果是，那证明你来对了！

这个项目灵巧而又暴力地翻译卡片里的所有内容，包括世界书，协议字段，凡是能找出来影响你查看的，都能抓出来保护翻译！

如果你经常处理带世界书、Lua、正则和资源的 AI 角色卡，应该遇到过这种情况：文字翻译了，按钮失效了，触发词丢了，协议也被改坏。卡片翻译工作台就是为这个场景做的：先识别卡片结构，再生成译文，最后让你在审核页决定哪些内容可以导出。

它可以独立运行，不依赖特定聊天前端，也不会自动修改原卡片或聊天记录。默认只监听 127.0.0.1，适合在自己的电脑上使用。

目录

• 项目简介
• 支持格式
• 功能
• 界面说明
• 最快上手：直接下载
• 快速开始
• 第一次使用
• 使用操作流程
• 翻译范围与保护规则
• 技术栈
• Docker 运维
• 本地开发
• 配置参考
• 数据与安全
• 贡献
• 许可证

项目简介

角色卡并不只是文本文件，通常还包含世界书、Lua、正则、变量、资源路径和自定义协议。直接对整张卡进行文本替换，可能导致按钮失效、触发词丢失或协议结构损坏。

工作台不会把整张卡直接丢给模型，而是先解析并保护程序结构，再生成翻译草稿。翻译范围由使用者选择，审核页会保留原文、机翻和人工定稿，存在疑点的内容可以单独复核。模型输出不直接覆盖原文件。

支持格式

本项目主要针对 RisuAI 模块（RISUM）和 CHARX 卡片开发，相关导入、解析、翻译、审核和导出流程经过较充分测试。PNG、普通 JSON 等酒馆卡格式目前只保留基础兼容能力，真实卡片覆盖不足，不能视为与 CHARX、RISUM 同等稳定。使用这些格式前请保留原文件，并自行核对导入结果与导出卡片。

格式	读取	导出	当前状态
CHARX	是	是	主要测试对象；支持 ZIP 容器、混合 JPEG+ZIP 和嵌入模块。
RISUM	是	是	主要测试对象；面向 RisuAI 模块 JSON 与资源容器。
JSON	基础	基础	兼容角色卡 JSON 和模块 JSON，但测试覆盖有限。
PNG	基础	基础	支持读写内嵌角色卡数据，但酒馆卡测试覆盖有限。
ST 预设	是	是	导入 SillyTavern 聊天补全预设（含 prompts / prompt_order）时按预设项目处理，导出为 RisuAI .risup 预设。

SillyTavern 预设转换说明

导入 ST 预设时会分析 prompt_order 的各个块并给出推荐块（RisuAI 预设只有一份提示词模板，多块时需要选一个）。转换遵循以下约定：

• 选中块的提示词顺序与启用状态完整保留；
• 被禁用、以及未被任何块引用的提示词（可选库）会转成 RisuAI 提示词开关，默认关闭，可在 RisuAI 中随时开启；
• role: model 按 ST 语义映射为 bot（RisuAI 自身会映射成 system，此处刻意不同）；
• SillyTavern 正则脚本按 placement 映射到 RisuAI 的输入/输出阶段；ST 中已禁用的正则不会被导入（RisuAI 正则没有启用开关，导入会改变行为）；
• 无法映射的字段和提示词会在转换报告中逐条列出，不会静默丢弃。

导出前建议在 RisuAI 中实际导入一次，核对开关面板与提示词顺序。

功能

能力	说明
多格式导入导出	以 CHARX、RISUM 为主要处理对象，同时保留 JSON、PNG 的基础兼容流程。
自定义翻译范围	角色主体、世界书、问候语、脚本界面、Lua 提示词和资源 JSON 均可按需选择。
独立任务调度	支持并发、批次和重试设置，失败项目可单独重试。
人工审核	并排查看原文、机器译文和人工定稿，通过后才写入审核稿。
结构保护	默认保护变量、Lua、正则、协议外壳、路径、URL、ID、资源文件名和按钮触发器。
世界书兼容	保留原始触发词，以追加别名方式写入目标语言关键词。
资源工作台	查看媒体和 JSON 引用；图片支持手动上传替换或图片编辑模型流程。

界面说明

主要页面如下：

• 概要：显示卡片格式、世界书、脚本和资源的识别结果。
• 字段：按路径查看待翻译文本及其保护状态。
• 任务：启动翻译、查看进度和失败原因，支持重试失败项。
• 审核：对照原文、机器译文和人工定稿，按状态或类型筛选并批量审核。
• 资源：查看资源引用、JSON 可见文字和图片处理候选。
• 协议：查看协议、Lua 和正则引用，确认翻译不会改变交互结构。

最快上手：直接下载

直接下载 Windows 桌面免安装版即可使用，无需安装 Node.js、Docker 或自行编译：前往 GitHub Releases 下载。

• 安装版：运行安装程序，按向导完成安装。
• 便携版：直接运行 EXE；程序数据保存在 EXE 同目录的 data/ 中，适合放在任意文件夹或移动硬盘使用。

CardLoom Translate Nightly 会随 master 的最新提交自动更新，适合获取最新构建；需要选择正式版本时，请查看 Tags 中带 v 前缀的版本。下载后启动程序，在浏览器打开显示的本地地址，再到左下侧“模型设置”填写模型接口和 API Key。

快速开始

推荐使用 Docker Compose 运行。部署前准备：

• Windows：Docker Desktop 与 Docker Compose v2。
• Linux：Docker Engine 与 Docker Compose v2。
• 开始翻译时需要一个兼容 OpenAI Chat Completions 的模型接口；模型配置在页面打开后完成。

1. 创建本地配置（可选）

Windows PowerShell：

if (-not (Test-Path .env)) { Copy-Item .env.example .env }
notepad .env

Linux：

[ -f .env ] || cp .env.example .env
nano .env

第一次使用可以不改 .env。启动页面后，点击左侧底部的“模型设置”，再填写 API Base URL、模型名称和 API Key；源语言、目标语言、并发和批次也在这里调整。需要图片汉化时，再填写图片编辑模型的接口、模型和 API Key。

模型配置由后端保存到本地 SQLite，API Key 由使用者自行配置，浏览器不会展示密钥内容。.env 只用于部署参数；模型、语言、并发、批次和图片设置不接受环境变量，必须在页面“模型设置”中填写。

2. 构建并启动

docker compose -f docker/compose.yml up -d --build

默认地址为 http://127.0.0.1:8787/。Compose 只映射本机回环地址，不会对局域网或公网开放端口。

3. 验证服务

Windows PowerShell：

Invoke-RestMethod http://127.0.0.1:8787/api/health
docker compose -f docker/compose.yml ps

Linux：

curl --fail --silent --show-error http://127.0.0.1:8787/api/health
docker compose -f docker/compose.yml ps

健康接口能返回 ok: true，就可以打开浏览器开始用了。

第一次使用

1. 打开左下侧“模型设置”，填写 API Base URL、模型名称和 API Key，并确认目标语言、并发和批次参数。
2. 点击“导入卡片 / 模块”，也可以直接把文件拖到页面里。
3. 点击“扫描卡片”或“扫描字段”，再在“概要”确认卡片结构、世界书、脚本和资源均已识别。
4. 在翻译范围下拉框里选择要处理的内容。默认的“全部翻译”会包含卡片可见文本、世界书、Lua 提示词、脚本界面和资源 JSON 可见文本。
5. 点击“开始翻译”，在“任务”页面查看进度、失败批次和质量提示。
6. 翻译完成后，确认无误可以点击“一键通过全部”；需要复核时点击“进入审核”，逐条确认原文、机器译文和人工定稿。一键通过只处理已有译文，不会通过未翻译或失败项。
7. 所有需要的译文通过后，点击“保存”只生成审核稿；点击“保存并导出”会保存审核稿、检查 Lua、脚本引用和卡片结构，校验通过后自动下载 JSON、PNG、CHARX 或 RISUM。

原始导入内容会一直保留在项目里。模型给出的只是草稿，只有审核通过的内容才会写进审核稿或导出文件。

PNG 和普通 JSON 目前提供基础导入导出支持；CHARX、RISUM 是本项目的主要支持格式。导出后请在目标客户端检查角色主体、世界书触发词、脚本和资源引用。

使用操作流程

推荐按下面的顺序处理一张卡：

1. 设置模型：打开左下侧“模型设置”，填写模型接口、模型名和 API Key；选择源语言、目标语言、并发和批次参数。
2. 导入原卡：选择 CHARX、RISUM、PNG 或 JSON 文件，也可以直接拖入页面。原始文件会保留在项目中，不会被覆盖。
3. 检查概要：确认卡片格式、角色主体、世界书、脚本、Lua、协议和资源数量符合预期。数量异常时暂停翻译流程。
4. 选择翻译范围：一般使用默认的“全部翻译”。如果只想处理主体或世界书，可以改用下拉框中的其他范围。
5. 扫描并开始翻译：点击“扫描卡片”或“扫描字段”，确认待翻译内容后点击“开始翻译”。大卡建议从较低并发和较小批次开始。
6. 处理失败任务：到“任务”页查看失败原因。修正配置或补充人工译文后再重试；结构性错误应先修正后再重试。
7. 选择审核方式：翻译完成后，已确认的内容可使用“一键通过全部”；需要复核的内容进入“审核”。“一键通过”仅处理已有译文，不处理未翻译或失败项。
8. 审核译文：在“审核”页对照原文、机器译文和人工定稿，优先处理带疑点、协议、脚本按钮、Lua 和世界书触发词的条目。
9. 保存、导出并回验：点击“保存”只生成审核稿；点击“保存并导出”会先检查 Lua、脚本引用和卡片结构，校验通过后自动下载目标格式。在实际使用的客户端重新打开，检查角色主体、世界书触发、按钮、弹窗、协议和资源引用。PNG、普通 JSON 尤其需要完成这一步。

遇到陌生协议或脚本时，在“协议”和“引用”页确认代码使用的文字，再决定是否通过；导出判断应同时依据结构校验和译文质量。

翻译范围与保护规则

范围	内容
只翻角色主体	名称、描述等主体字段。
主体 + 世界书 + 问候语	加入世界书和开场白。
包含脚本按钮 / 弹窗	加入明确可见的脚本界面文字。
完整可见内容	处理卡片、世界书、脚本界面和 Lua 提示词的可见文字。
全部翻译	再加入 CHARX 内部 JSON 的可见字符串；为默认项。
仅 Lua 解析提取	只处理 Lua 中识别为可见文字的字符串。

默认情况下，变量名、ID、路径、URL、正则、Lua 结构、协议外壳和按钮触发器不会被改写。遇到不熟悉的协议，应先在“协议”和“审核”页面完成确认，再决定是否批量通过。

Docker 运维

平时用到的 Docker 命令基本就是下面几条。数据会留在 Compose 的数据卷里，停掉容器不会把项目删掉。

停止服务但保留数据：

docker compose -f docker/compose.yml down

更新代码后重新构建并启动：

docker compose -f docker/compose.yml up -d --build

查看日志：

docker compose -f docker/compose.yml logs --tail=200

如果 8787 已经被别的程序占用，可以在 .env 里换一个本机端口：

WORKBENCH_BIND_PORT=18880

随后重新执行 docker compose -f docker/compose.yml up -d，并访问 http://127.0.0.1:18880/。端口映射应保持在回环地址，不应设置为 0.0.0.0 或直接暴露到公网。

Windows、Linux、备份和恢复的完整说明放在部署说明里。

技术栈

• 前端：React、TypeScript、Vite、Lucide。
• 后端：TypeScript、Fastify、SQLite Worker。
• 模型接口：兼容 OpenAI Chat Completions 的服务；模型配置在页面中完成。
• 部署：Docker Compose 或 Node.js 本地进程。

本地开发

本地开发需要 Node.js 22 或更高版本：

npm ci
npm test
npm run build
npm run dev

开发页面默认位于 http://127.0.0.1:5173/，开发 API 默认位于 http://127.0.0.1:8787/。

要验证生产构建，可以运行：

npm run build
npm start

Windows 桌面版

需要在 Windows 上执行以下命令：

# 生成便携版：release/CardLoom-Translate-Portable-<version>.exe
npm run desktop:portable

# 生成安装版：release/CardLoom-Translate-Setup-<version>.exe
npm run desktop:installer

# 一次生成两种版本
npm run desktop:all

便携版把 SQLite、上传文件和缓存放在 EXE 同目录的 data/；安装版把这些数据放在 Electron 的 Windows 用户数据目录。两种版本都只在本机 127.0.0.1 启动服务。

推送到 GitHub 后，.github/workflows/desktop-release.yml 会自动编译这两种 EXE，并将构建产物上传到 Actions 运行记录。推送到 master 的普通提交会自动更新一个可下载的 CardLoom Translate Nightly 预发布版本；正式版本应先同步推进 package.json 与 package-lock.json 的版本号，再推送同号 v 前缀标签（例如 v0.1.3）。工作流会校验标签与包版本一致，创建独立的正式 GitHub Release，并永久保留带版本号的安装包；旧版本不会被 Nightly 覆盖。

当前 Actions 产物未配置 Windows 代码签名证书，首次运行可能显示“未知发布者”；这不影响程序启动。后续配置证书 Secret 后再开启签名即可。

Linux 临时改端口：

WORKBENCH_HOST=127.0.0.1 WORKBENCH_PORT=18880 npm start

Windows PowerShell 临时改端口：

$env:WORKBENCH_HOST = '127.0.0.1'
$env:WORKBENCH_PORT = '18880'
npm start

配置参考

端口、数据目录等部署参数放在仓库根目录的 .env 里；API Base URL、模型、API Key、语言、并发、批次和图片设置只能从页面左侧底部的“模型设置”完成。.env 只用于部署参数，不接受 TRANSLATION_* 或 IMAGE_EDIT_* 配置，也不会把任何模型设置写入 SQLite。页面保存的模型配置会写入本地 SQLite；API Key 由使用者自行配置且仅由后端读取，浏览器不会展示密钥内容。

官方接口示例

下面只列出公开的官方接口示例，不代表项目当前配置。模型名称和 API Key 应在页面“模型设置”中自行配置：

服务商	API Base URL	模型	API Key
DeepSeek	https://api.deepseek.com	自行填写，例如 deepseek-v4-flash	自行配置
OpenAI	https://api.openai.com/v1	自行填写	自行配置

DeepSeek 的 OpenAI 兼容 Base URL 以其官方文档为准；如果服务商要求完整地址，也可以填写对应的 /chat/completions 地址。

页面参数可按下面的值开始，再根据卡片大小和模型服务商限制调整：

页面设置	示例值
源语言	auto
备用语言	en
目标语言	zh-CN
并发数	8（无固定上限）
每批段落数	8（无固定上限）
每批字符数	40000（无固定上限）
图片编辑 API、Key、模型	自行配置

变量	作用	默认值
WORKBENCH_HOST	本地 Node.js 监听地址	127.0.0.1
WORKBENCH_PORT	应用内部监听端口	8787
WORKBENCH_BIND_PORT	Docker 宿主机端口	8787
WORKBENCH_UPLOAD_LIMIT_MB	单个上传大小；0 表示不额外限制	0
WORKBENCH_DB_WORKERS	SQLite Worker 数量	3

正文翻译与阶段 2 共用同一模型请求通道。并发和批次参数只校验为正整数，没有产品固定上限；数值越大，内存占用、接口费用、上下文长度和限流风险越高，请根据模型服务商实际能力自行调整。

数据与安全

• 本地 Node.js 默认把 SQLite、上传卡片、草稿和缓存放在 data/；Docker 使用 Compose 命名卷。两种方式默认不是同一份数据，切换时看不到另一边的项目是正常的。
• 当前没有登录功能，默认只适合本机使用。服务应保持 127.0.0.1 绑定；远程访问必须通过可信反向代理提供认证、TLS 和访问控制。
• 升级、切换部署方式、批量导出或清理数据前，应备份重要项目。尤其注意：docker compose down -v 会删除 Compose 数据卷。
• 陌生卡片导出前，应再次检查 Lua、正则、协议、世界书触发词和资源引用。工作台的保护规则仅作辅助，不能替代人工确认。

贡献

格式兼容、解析或翻译保护问题请提交 Issue；附上脱敏后的日志和最小复现样例有助于定位。提交代码前需：

1. 模型 Key、导入卡片、SQLite、备份和日志不得进入提交。
2. 为解析、保护规则、导出或调度逻辑补充相应回归测试。
3. 运行 npm test 与 npm run build。
4. 遵循 AGENTS.md 中的代码边界和验证约定。

许可证

本项目采用 GNU GPL v3.0 或更高版本 发布。复制、修改和再分发本项目时，请遵守许可证及其源码提供要求。