docuseal/简体中文支持部署指南.md

# DocuSeal 简体中文支持部署指南

## 概述

本文档记录了为 DocuSeal 开源电子签名平台添加完整简体中文（zh-CN）支持的整个过程，包括后端 Rails i18n 翻译、前端 Vue 组件翻译、Dockerfile 国内镜像源适配，以及语言选项统一。

## 修改文件清单

| 文件 | 变更量 | 说明 |
|------|--------|------|
| `config/locales/i18n.yml` | +1070 行 | 新增 zh-CN 区域，完整中文翻译 |
| `app/javascript/submission_form/i18n.js` | +111 行 | 新增前端提交表单 zh 翻译对象 |
| `app/javascript/template_builder/i18n.js` | +226 行 | 新增前端模板编辑器 zh 翻译对象 |
| `app/controllers/accounts_controller.rb` | +16 行 | 统一语言选项列表 |
| `config/application.rb` | +1 行 | 添加 zh-CN 到可用语言列表 |
| `Dockerfile` | +19 行 | 添加国内镜像源加速构建 |
| `docker-compose.yml` | 版本锁定 | 锁定 PostgreSQL 和 Caddy 版本 |

---

## 一、i18n 中文翻译详情

### 1.1 后端 Rails 翻译（config/locales/i18n.yml）

在文件末尾（第 8088 行）新增 `zh-CN` 语言区域，采用 YAML 锚点继承模式：

```yaml
zh-CN:
  <<: *en          # 继承所有英文键作为回退
  language_zh-CN: 中文 (简体)
  sign_in: 登录
  # ... 1000+ 条中文翻译
```

翻译覆盖范围：
- 登录/注册/密码重置流程
- 账户设置、偏好设置
- 文档模板管理（创建、编辑、归档）
- 签署流程（签名请求、提醒、完成通知）
- 邮件模板（签名请求邮件、提醒邮件、完成通知）
- 表单字段类型（文本、签名、日期、选择框等）
- API 参考、嵌入集成
- Webhook、SSO、SAML 配置
- 应用导览、分页
- 订阅计划、账单
- Devise 认证系统
- Doorkeeper OAuth 授权
- 所有系统通知/提示消息

**技术要点：**
- 使用 `<<: *en` 继承英文键，未翻译的键自动回退英文
- 配合 `config.i18n.fallbacks = [:en]` 双重保障
- 保留了所有插值变量（`%{name}`, `%{count}` 等）和 HTML 标签

### 1.2 前端提交表单翻译（app/javascript/submission_form/i18n.js）

新增 `zh` 翻译对象（107 个键），覆盖：
- 表单进度提示
- 签名绘制操作（手绘、输入、上传）
- 字段类型名称
- 身份验证流程（短信/邮件验证码）
- 文件上传操作
- 支付界面

关键代码：
```js
const zh = {
  step: '步骤',
  sign_and_complete: '签署并完成',
  draw_signature: '绘制签名',
  // ... 107 个翻译键
}
const i18n = { en, es, it, de, fr, pl, uk, cs, pt, he, nl, ar, ko, ja, zh }
```

**技术要点：**
- 前端 locale 解析：`I18n.locale.to_s.split('-').first` → `"zh"`，匹配 `i18n["zh"]`
- 回退链：`i18n[locale] → i18n[browserLang] → i18n.en → key`

### 1.3 前端模板编辑器翻译（app/javascript/template_builder/i18n.js）

新增 `zh` 翻译对象（221 个键），覆盖：
- 字段绘制和编辑操作
- 参与方管理（第1-20方）
- 字段属性设置（字体、对齐、验证等）
- 条件逻辑配置
- 公式编辑器
- 修订版本管理
- PDF 密码保护

关键代码：
```js
const zh = {
  fixed: '固定',
  draw_field_on_the_document: '在文档上绘制字段',
  // ... 221 个翻译键
}
export { en, es, it, pt, fr, de, nl, zh }
```

### 1.4 语言选项统一

`config/application.rb` 中 `available_locales` 包含 zh-CN（完整 22 种语言）。

`accounts_controller.rb` 中 `LOCALE_OPTIONS` 从原来的 9 种扩展到 22 种，与 `available_locales` 完全一致：

```ruby
LOCALE_OPTIONS = {
  'en-US' => 'English (United States)',
  'en-GB' => 'English (United Kingdom)',
  'fr-FR' => 'Français',
  'es-ES' => 'Español',
  'pt-PT' => 'Português',
  'de-DE' => 'Deutsch',
  'it-IT' => 'Italiano',
  'nl-NL' => 'Nederlands',
  'zh-CN' => '中文 (简体)',
  'es' => 'Español',
  'it' => 'Italiano',
  'de' => 'Deutsch',
  'fr' => 'Français',
  'nl' => 'Nederlands',
  'pl' => 'Polski',
  'uk' => 'Українська',
  'cs' => 'Čeština',
  'pt' => 'Português',
  'he' => 'עברית',
  'ar' => 'العربية',
  'ko' => '한국어',
  'ja' => '日本語'
}.freeze
```

---

## 二、Dockerfile 国内镜像源适配

### 2.1 修改内容

| 构建阶段 | 包管理器 | 原地址 | 替换为国内镜像 |
|---------|---------|--------|---------------|
| download | Alpine apk | `dl-cdn.alpinelinux.org` | `mirrors.tuna.tsinghua.edu.cn` |
| webpack | Alpine apk | `dl-cdn.alpinelinux.org` | `mirrors.tuna.tsinghua.edu.cn` |
| webpack | RubyGems | `rubygems.org` | `gems.ruby-china.com` |
| webpack | Yarn/npm | `registry.yarnpkg.com` | `registry.npmmirror.com` |
| app | Alpine apk | `dl-cdn.alpinelinux.org` | `mirrors.tuna.tsinghua.edu.cn` |
| app | Bundler | `rubygems.org` | `gems.ruby-china.com` |

### 2.2 关键代码位置

**Alpine apk 镜像**（3 个阶段均添加）：
```dockerfile
RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apk/repositories
```

**RubyGems 镜像**（webpack 阶段）：
```dockerfile
gem sources --remove https://rubygems.org/ && \
gem sources -a https://gems.ruby-china.com/
```

**Bundler 镜像**（app 阶段）：
```dockerfile
bundle config set --global mirror.https://rubygems.org https://gems.ruby-china.com
```

**Yarn 镜像**（webpack 阶段）：
```dockerfile
yarn config set registry https://registry.npmmirror.com
```

### 2.3 GitHub 资源下载说明

以下资源仍直接从 GitHub 下载（未走镜像），因为它们通常通过 HTTPS 443 端口可以正常访问：

| 资源 | 大小 | 用途 |
|------|------|------|
| GoNotoKurrent 字体（Regular + Bold） | ~30MB | 文档默认字体 |
| DancingScript 字体 | ~200KB | 签名字体 |
| ONNX 模型文件 | ~10MB | 表单字段自动检测 |
| PDFium 二进制包 | ~30MB | PDF 渲染引擎 |

如果 GitHub 下载仍然超时，可手动下载后通过 Docker volume 挂载，或使用 `ghproxy.net` 等 GitHub 文件代理。

---

## 三、构建与部署

### 3.1 构建 Docker 镜像

```bash
cd /home/new211/my_project/DocuSeal/docuseal

# 构建镜像（首次约 15-30 分钟）
docker build -t docuseal-zh:latest .

# 如需完全重新构建（不使用缓存）
docker build -t docuseal-zh:latest . --no-cache
```

### 3.2 修改 docker-compose.yml

```yaml
services:
  app:
    depends_on:
      postgres:
        condition: service_healthy
    image: docuseal-zh:latest              # 改为本地构建的镜像
    # image: docuseal/docuseal:latest       # 原始镜像（无中文）
    ports:
      - 3000:3000
    volumes:
      - ./docuseal:/data/docuseal
    environment:
      - FORCE_SSL=${HOST}
      - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/docuseal

  postgres:
    image: postgres:17.5
    volumes:
      - './pg_data:/var/lib/postgresql/18/docker'
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: docuseal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
```

### 3.3 启动服务

```bash
# 创建数据目录
mkdir -p ./docuseal ./pg_data

# 启动
docker compose up -d

# 查看日志
docker compose logs -f app
```

访问 `http://localhost:3000` 即可使用。

### 3.4 本地开发模式（不依赖 Docker）

```bash
# 前提：已安装 Ruby 4.0+、Node.js、PostgreSQL、Yarn

# 安装依赖
bundle install
yarn install

# 编译前端
bin/shakapacker

# 准备数据库
bin/rails db:prepare

# 启动
bin/rails server
```

---

## 四、验证方法

### 4.1 快速验证（无需启动服务）

```bash
# 1. 验证 YAML 格式
ruby -ryaml -e "YAML.load_file('config/locales/i18n.yml')" && echo "YAML 格式正确"

# 2. 验证前端 JS 翻译键数量
node -e "import('./app/javascript/submission_form/i18n.js').then(m => console.log('zh 键数:', Object.keys(m.default.zh).length))"
node -e "import('./app/javascript/template_builder/i18n.js').then(m => console.log('zh 键数:', Object.keys(m.zh).length))"

# 3. 确认 zh-CN 已注册到可用语言列表
grep "zh-CN" config/application.rb
grep "zh-CN" app/controllers/accounts_controller.rb
```

预期输出：
- YAML 格式正确
- submission_form zh 键数: **106**
- template_builder zh 键数: **221**
- 两个 grep 命令均有输出

### 4.2 功能验证清单

启动服务后，按以下清单验证：

| 序号 | 页面 | 操作 | 预期结果 |
|------|------|------|---------|
| 1 | 登录页 `/` | 点击语言下拉菜单 | 显示 **中文 (简体)** 选项 |
| 2 | 登录页 | 选择中文 | 整个界面切换为中文 |
| 3 | 注册页 `/sign_up` | 查看表单 | 字段标签显示中文 |
| 4 | 登录后首页 | 查看导航 | 菜单项显示中文 |
| 5 | 模板创建 | 创建新模板 | 编辑器界面显示中文 |
| 6 | 模板编辑器 | 拖放字段 | 字段名称、设置面板显示中文 |
| 7 | 模板编辑器 | 查看参与方 | 第一方/第二方等显示中文 |
| 8 | 发送文档 | 添加收件人 | 表单和按钮显示中文 |
| 9 | 签署页面 | 以签署者身份打开 | 签名操作、按钮显示中文 |
| 10 | 账户设置 `/settings/account` | 查看语言下拉 | 包含完整 22 种语言选项 |
| 11 | 邮件模板 | 查看邮件设置 | 模板变量说明显示中文 |
| 12 | API 参考 | 查看 API 文档 | 界面显示中文 |

---

## 五、翻译回退机制

当某个翻译键在 `zh-CN` 中未定义时，系统按以下优先级查找：

```
zh-CN 翻译 → 英文翻译（en）→ 原始键名
```

具体实现：

1. **后端 Rails**：`config.i18n.fallbacks = [:en]` + YAML `<<: *en` 锚点继承
2. **前端提交表单**：`this.i18n[key] || i18n[lang]?.[key] || i18n[browserLang]?.[key] || i18n.en[key] || key`
3. **前端模板编辑器**：同上逻辑

---

## 六、常见问题

### Q1：切换中文后部分文字仍显示英文？

**原因**：前端 JS 翻译键缺失。检查对应 Vue 组件的 i18n.js 文件中是否有对应的 `zh` 键。

**解决**：在 `app/javascript/submission_form/i18n.js` 或 `template_builder/i18n.js` 的 `zh` 对象中补充缺失的键。

### Q2：Docker 构建时 GitHub 下载超时？

**原因**：国内网络访问 GitHub 不稳定。

**解决方案（按优先级）**：

1. 使用代理构建：
   ```bash
   docker build --build-arg HTTP_PROXY=http://your-proxy:port \
                --build-arg HTTPS_PROXY=http://your-proxy:port \
                -t docuseal-zh:latest .
   ```

2. 手动下载资源文件，修改 Dockerfile 使用 `COPY` 替代 `wget`

3. 尝试不同的 GitHub 镜像代理（在 `wget` URL 前加前缀）：
   - `https://ghproxy.net/` 或 `https://ghproxy.com/`
   - `https://mirror.ghproxy.com/`

### Q3：如何添加更多中文语言变体（如 zh-TW 繁体中文）？

```bash
# 1. 复制 zh-CN 翻译作为基础
# 2. 修改为繁体中文
# 3. 在 config/application.rb 的 available_locales 中添加 :'zh-TW'
# 4. 在 accounts_controller.rb 的 LOCALE_OPTIONS 中添加
# 5. 在前端 i18n.js 中添加 zh-TW 翻译对象
```

### Q4：如何只构建前端翻译（不重新构建整个 Docker 镜像）？

```bash
# 本地开发模式重新编译前端
bin/shakapacker

# 或者只重编译前端资源
yarn install && bin/shakapacker
```

---

## 七、文件变更完整差异

如需查看所有变更的完整差异：

```bash
git diff HEAD -- \
  config/locales/i18n.yml \
  app/javascript/submission_form/i18n.js \
  app/javascript/template_builder/i18n.js \
  app/controllers/accounts_controller.rb \
  config/application.rb \
  Dockerfile
```

---

> **文档版本**：1.0
> **最后更新**：2026-05-18
> **适用版本**：DocuSeal (master branch)