|
|
|
|
@ -0,0 +1,397 @@
|
|
|
|
|
# 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)
|
new985211
1 month ago