adminbruno
/
docuseal
mirror of https://github.com/docusealco/docuseal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '5c88f1a73f'
${ noResults }
docuseal/简体中文支持部署指南.md

11 KiB
Raw Blame History Escape

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 锚点继承模式：

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 个键），覆盖：

  • 表单进度提示
  • 签名绘制操作（手绘、输入、上传）
  • 字段类型名称
  • 身份验证流程（短信/邮件验证码）
  • 文件上传操作
  • 支付界面

关键代码：

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 密码保护

关键代码：

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 完全一致：

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 个阶段均添加）：

RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.tuna.tsinghua.edu.cn/g' /etc/apk/repositories

RubyGems 镜像（webpack 阶段）：

gem sources --remove https://rubygems.org/ && \
gem sources -a https://gems.ruby-china.com/

Bundler 镜像（app 阶段）：

bundle config set --global mirror.https://rubygems.org https://gems.ruby-china.com

Yarn 镜像（webpack 阶段）：

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 镜像

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

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 启动服务

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

# 启动
docker compose up -d

# 查看日志
docker compose logs -f app

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

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

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

# 安装依赖
bundle install
yarn install

# 编译前端
bin/shakapacker

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

# 启动
bin/rails server

四、验证方法

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

# 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. 使用代理构建：

    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 繁体中文）？

# 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 镜像）？

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

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

七、文件变更完整差异

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

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)