PMO自动化系统英文化改造：最小影响路径与多语言数据架构设计

PMO自动化系统英文化改造：最小影响路径与多语言数据架构设计

问题背景

PMO Auto Monday 是我们为项目管理办公室搭建的每周自动化任务系统。每周一早上，它会根据项目状态自动生成报告、发送提醒、推动审批流程。这个系统从第一天起就是纯中文环境——数据库字段、脚本消息、工作流节点描述，全是中文。

去年Q4，业务方提出需求：系统需要支持英文团队使用。同一个实例，同一个数据库，但不同的人看到不同的语言。业务方的预期是「加个开关就行」，但当我们真正去评估改动范围时，发现这条链路比我们预想的深得多。改动不只涉及界面层，还包括：数据库里 47 张表的中文字段、23 个 Python 脚本中的硬编码提示语、以及 n8n 工作流里嵌入的文案。总涉及范围超过 300 个独立项。

为什么这个决策难做

我们一开始以为英文化是「把所有中文替换成英文变量引用」。找到中文字符串，逐个替换成 i18n key，看起来工作量可控。但实际上，每替换一个点，都会触发连锁反应。

比如数据库里的状态字段 待审批，脚本中有大量这样的判断逻辑：

if status == "待审批":
    send_reminder()

如果直接改成 if status == "pending"，英文环境能工作，但中文环境彻底失效。反过来也一样。这意味着「替换」思路在逻辑层根本走不通——两种语言不能共存于同一个硬编码值里。

我们还低估了工作流层的耦合度。n8n 的 HTTP Request 节点里硬编码了中文的 header 值，Switch 节点的条件分支里写了中文判断。这些节点在运行时读取的是实时数据，修改它们需要暂停整个工作流。

更棘手的是「增量切换」的需求：业务不能接受一次性全量切换，必须先在测试环境验证，再逐步扩展到生产。这意味着系统要在一段时间内同时支持两种语言环境。这让原本看似简单的「改完上线」变成了「改完还要同时跑两套」的系统工程。

根因/核心设计决策

问题的本质是语言逻辑和业务逻辑没有分离。中文不是数据，它是逻辑的一部分——脚本靠中文字符值做判断，数据库靠中文字段名存储状态，工作流靠中文文案流转。这种耦合让语言切换变成了系统重构，而非配置变更。

我们最终采用的是「三层解耦」改造路径：

第一层：数据层——语言值与业务值分离

数据库不再存储中文状态值，而是存储语义化的 code 值。原来的 待审批 变成 pending，已完成 变成 completed。这是一次性的数据迁移，需要写一个映射脚本：

# status_migration.py
import yaml

with open('status_mapping.yaml') as f:
    mapping = yaml.safe_load(f)['status']

for table in ['project_info', 'task_log', 'approval_records']:
    for old_val, new_val in mapping.items():
        db.execute(
            f"UPDATE {table} SET status = %s WHERE status = %s",
            (new_val, old_val)
        )

# status_mapping.yaml
status:
  待审批: pending
  进行中: in_progress
  已完成: completed
  已阻塞: blocked

迁移完成后，所有业务代码不再出现中文字符串。语言翻译全部在展示层处理。

第二层：脚本层——语言资源外部化

脚本中的提示语、错误消息、邮件正文全部迁移到语言资源文件。脚本只引用 key，不包含任何语言文本：

# msg_templates/en.yaml
reminder:
  subject: "Weekly Review Reminder"
  body: "Project {project} status review is due."
  
# msg_templates/zh.yaml  
reminder:
  subject: "周例会提醒"
  body: "项目 {project} 状态评审待完成。"

# send_reminder.py
def get_template(lang, key):
    with open(f'msg_templates/{lang}.yaml') as f:
        return yaml.safe_load(f)[key]

def send_reminder(project_id):
    lang = get_user_lang(project_id)  # 从用户配置读取语言偏好
    tpl = get_template(lang, 'reminder')
    
    message = tpl['body'].format(project=get_project_name(project_id))
    email.send(to=get_user_email(project_id), 
               subject=tpl['subject'], 
               body=message)

这里的关键设计是：语言选择是从用户配置/请求头/环境变量读取的，不是硬编码在脚本里的。同一个函数，调用一次走英文路径，调用一次走中文路径。

第三层：工作流层——配置参数化

n8n 里的工作流节点不再硬编码中文。Subnode 调用时传递语言参数，节点内部根据参数动态渲染文案。原有的中文 HTTP Header 改成从 workflow variables 读取：

{
  "nodes": [
    {
      "name": "Send Reminder",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "={{$vars.api_base}}/notify",
        "method": "POST",
        "body": {
          "subject": "={{$vars.lang === 'en' ? 'Weekly Review' : '周例会提醒'}}",
          "project": "={{$json.project_name}}"
        }
      }
    }
  ]
}

可移植的原则

1. 如果你在做多语言改造，先做数据层迁移，再做展示层适配。把语义化的 code 值作为主存储，语言翻译只存在于展示层，这是避免两套逻辑打架的根本。
2. 如果你在设计新系统，从第一天就把语言资源文件化。不要在代码里写任何可显示文本，中文英文都写成 key-value 引用。开发时多花 5 分钟，未来迁移时省 50 小时。
3. 如果你要同时跑双语言环境，语言选择必须在调用链的最前端完成。不要在中间层再判断语言——用户的语言偏好应该在请求入口就确定，后续所有函数只传递语言标识符。
4. 如果你改造的是脚本系统，检查所有业务判断是否依赖语言值。脚本中的 if status == "待审批" 是技术债，不是功能。改成语义化的 code 值，让业务逻辑和语言解耦。
5. 如果你在处理工作流引擎，把所有文案相关节点改成参数化。节点的 Switch 条件、邮件模板、HTTP Header，都应该是变量的组合，而不是硬编码的字符串。

结尾

PMO Auto Monday 的英文化改造用了三周完成，比最初预估多了一周——多出的时间主要花在清理散落在各处的硬编码语言逻辑上。但改造完成后，系统扩展新语言的成本大幅降低：要支持日文、德文，只需要新增语言资源文件，代码层不需要任何改动。如果你的系统也面临类似的多语言需求，建议从数据架构梳理开始——语言层的复杂度往往反映了数据层的设计问题。