数据库参数国际化：从 13 个迁移学到的设计原则

数据不该懂语言

数据库参数有一个字段叫 config_schema。里面存储的是 JSON，定义了 AI 模型的可配置参数。

某一天，你发现这个 JSON 中的 label 和 ui:description 字段都是中文：

{
  "prompt": {
    "label": "提示词",
    "ui:description": "描述你想生成的视频内容，最多 2000 个字符"
  }
}

这看起来没问题。直到你需要支持英文界面。或者日文。或者任何非中文的语言。

数据库不该懂语言。数据是结构，不是展示。当你把展示层的语言硬编码到数据层，系统的边界就被锁死了。

国际化不是"添加多语言支持"，是系统设计的底层约束。

对齐的本质

我们有 13 个 AI 模型需要参数对齐。从 ByteDance V1 Lite 到 Google Veo-3 HD，每个模型的 config_schema 都嵌入了中文。

对齐不是翻译。翻译是把"提示词"变成"Prompt"。对齐是重新定义系统边界——数据层不应该知道展示层用什么语言。

这次迁移的目标：

1. 将所有中文标签和描述替换为英文
2. 确保参数符合官方 API 文档
3. 保持迁移的幂等性和可验证性

为什么选择英文作为数据层的默认语言？因为英文是 API 文档的标准语言。数据层的职责是准确反映 API 契约，不是服务特定语言的用户。

迁移的设计原则

13 个迁移文件，每个文件对应一个模型。迁移不是一次性脚本，是系统演进的历史记录。

原则 1：幂等性

每个迁移都可以安全地重复执行。

-- 错误的写法
UPDATE ai_models SET config_schema = ...;

-- 正确的写法
UPDATE ai_models
SET config_schema = ...
WHERE api_identifier = 'specific-model-id';

幂等性来自精确的 WHERE 子句。不是"更新所有模型"，是"更新这一个特定模型"。

原则 2：可验证性

每个迁移执行后，立即验证结果。

-- 执行迁移
UPDATE ai_models SET ...;

-- 验证结果
SELECT
  api_identifier,
  config_schema->'properties'->'prompt'->>'label' as prompt_label
FROM ai_models
WHERE api_identifier = 'specific-model-id';

验证查询不是可选项，是迁移的一部分。如果验证失败，迁移就是失败的。

原则 3：小步前进

一个迁移只改一个模型。不是"一次更新 13 个模型"，是"13 次迁移，每次更新 1 个模型"。

为什么？因为出错时容易定位。如果第 7 个迁移失败了，你知道问题在哪。如果一次更新 13 个，你不知道是哪个模型的参数有问题。

从 13 个迁移学到的

这次迁移涉及 13 个模型：

• ByteDance V1 Lite (文本转视频 + 图像转视频)
• Kling V2.1 (Master, Standard, Pro)
• WAN 2.2 A14B (文本转视频 + 图像转视频)
• OpenAI Sora 2 (文本转视频 + 图像转视频)
• Runway Gen-3 Alpha Turbo
• Google Veo-3 (Fast + HD)

每个模型的参数都有细微差异。Kling 支持 negative_prompt，Sora 不支持。Veo-3 有独特的 quality 参数，WAN 有 seeds 数组。

关键教训：不要假设参数是一致的。

即使都是"文本转视频"模型，参数也不完全相同。迁移不是批量操作，是逐个确认。

验证比执行更重要

迁移的核心不是 UPDATE 语句，是验证查询。

每个迁移文件的结构：

-- 1. 执行更新
UPDATE ai_models
SET
  config_schema = jsonb_set(...),
  description = 'English description'
WHERE api_identifier = 'model-id';

-- 2. 验证结果
SELECT
  api_identifier,
  name,
  config_schema->'properties'->'prompt'->>'label' as prompt_label,
  config_schema->'properties'->'prompt'->>'ui:description' as prompt_desc
FROM ai_models
WHERE api_identifier = 'model-id';

验证查询回答三个问题：

1. 迁移是否执行成功？
2. 数据是否符合预期？
3. 如果失败，问题出在哪？

没有验证的迁移，就是盲目的变更。你不知道它做了什么，也不知道它是否成功。

国际化是底层约束

13 个迁移执行完成后，数据库中的所有参数标签和描述都变成了英文。

但这不是终点。

下一步需要在展示层实现真正的国际化：

1. 前端从 i18n 文件加载翻译
2. 根据用户语言偏好动态渲染
3. 数据层保持语言无关

数据层定义"有哪些参数"，i18n 文件定义"参数叫什么"。职责分离，边界清晰。

国际化不是后期添加的功能，是系统设计时就要考虑的约束。如果数据层从一开始就嵌入了语言，重构的成本会很高。

这次 13 个迁移就是代价。

最后

数据不该懂语言。

当你在数据库中存储"提示词"而不是"prompt"，当你在 JSON 中硬编码中文描述，你就在数据层和展示层之间埋下了耦合。

系统的边界应该清晰：

• 数据层：语言无关，契约驱动
• 业务层：逻辑处理，规则验证
• 展示层：用户体验，多语言支持

国际化不是翻译工作，是系统设计的底层约束。

如果你的数据库参数还在说中文，现在是重新定义边界的时候了。