如何构建用于管理本地化与翻译的 Web 应用

Web 应用应解决的问题

本地化管理是让产品文本（有时还包括图片、日期、货币和格式化规则）被翻译、审核、批准并发布的日常工作——前提是不破坏构建或让用户困惑。

对产品团队来说，目标不是“把一切都翻译完”。而是当产品变化时，让每种语言版本都保持准确、一致并且及时更新。

你要修复的问题

大多数团队出发时怀着好意，最后却变成一团乱：

• 离散的语言文件 分散在仓库、文件夹和表格里，没有单一可信来源。

• 用词不一致（“Sign in” vs “Log in”）、重复字符串，以及相同概念的不同翻译。

• 审核周期慢，因为反馈散落在邮件线程、评论或聊天里。

• 状态不明确：没人知道哪些已翻译、哪些过时、哪些能安全发布。

• 危险的手动步骤 在导入/导出时会丢失键、破坏占位符或误覆盖。

目标用户

一个有用的本地化管理 Web 应用应支持多种角色：

• 开发者 需要可靠的字符串更新、简洁的 diff 和更少的合并冲突。
• 翻译人员 需要上下文、术语指南和一个聚焦的工作队列。
• 审查者 需要清晰的批准流程并能对具体字符串评论。
• PM 和本地化负责人 需要进度可见性和可信的截止日。

你最终会构建的内容

你将构建一个 MVP，将字符串集中管理、按语言跟踪状态，并支持基本的审核和导出。更完整的系统会加入自动化（同步、QA 检查）、更丰富的上下文以及像术语表和翻译记忆这样的工具。

定义范围与 MVP 功能

在设计表格或界面前，先决定你的本地化管理 Web 应用实际上负责什么。紧凑的范围让首版可用——也能避免后来重做一切。

先列出内容类型

翻译内容通常不只存在一个地方。写下从第一天起需要支持的内容：

• UI 字符串（产品标签、按钮、错误信息）
• 事务性邮件（主题与模板）
• 文档片段（短的可复用块，而不是整站文档）
• 营销页面（通常由不同团队拥有，审核需求不同）

这能避免“一套工作流适用于所有场景”的误区。例如，营销文案可能需要额外批准，而 UI 字符串需要快速迭代。

决定 MVP 要支持的文件格式

为 MVP 选 1–2 个格式，然后再扩展。常见选项包括 JSON, YAML, PO, CSV。实际可行的 MVP 选择是 JSON 或 YAML（用于应用字符串），如果你已依赖表格导入，则额外支持 CSV。

明确一些需求，例如复数形式、嵌套键和注释。这些细节会影响语言文件管理和未来的导入/导出可靠性。

选择语言与回退规则

定义一个源语言（通常是 en）并设置回退行为：

• 缺失字符串回退到 en
• 可选地回退到父语言（例如 pt-BR → pt → en）

还要决定每种语言的“完成”标准：100% 翻译、审核完毕还是已发布。

MVP 与后续功能

MVP 聚焦于翻译审核流程和基本 i18n 工作流：创建/编辑字符串、分配任务、审核与导出。

规划后续要点——截图/上下文、术语表、翻译记忆基础 和 集成机器翻译——但在用真实内容验证核心工作流之前不要构建它们。

设计数据模型

本地化应用成败取决于数据模型。如果底层实体和字段清晰，其他一切（UI、工作流、集成）都会变得更简单。

从核心实体开始

大多数团队用一小套表/集合就能覆盖 80% 的需求：

• Project：一个产品/应用或一片字符串空间。
• Locale：语言与地区变体（例如 en, en-GB, pt-BR）。
• Key：代码中使用的稳定标识符（checkout.pay_button）。
• Source string：附着在 key 上的参考文本（通常为基准语言）。
• Translation：某 key 在某 locale 下的本地化值。
• Version：一次发布、导入或文件修订的快照边界。

把关系建模清楚：一个 Project 有多个 Locales；一个 Key 属于一个 Project；一个 Translation 属于一个 Key 和一个 Locale。

用状态字段编码工作流

为每个翻译加上状态，这样系统能引导人力：

• draft → in_review → approved
• 对于不应发布的字符串使用 blocked（法律审核、缺少上下文等）

把状态变化记录为事件（或历史表），以后就能回答“谁在什么时候批准了它？”这类问题。

存储防错的元数据

翻译需要的不仅仅是纯文本。捕获：

• 占位符（例如 {name}, %d）以及它们是否必须与源匹配
• 最大长度（按钮和 UI 约束）
• 上下文说明（出现位置、含义、语气）
• 标签（功能区、平台、紧急度）

不要跳过审计字段

至少保存：created_by, updated_by, 时间戳和简短的 change_reason。这能让审核更快，并在团队对比应用内与已发布内容时建立信任。

规划存储与版本控制

存储决策会影响一切：编辑 UX、导入/导出速度、差异比较，以及你对发布的信心。

存字符串：逐键一行 vs 整文件文档

逐键一行（每个字符串键每个语言一行）适合仪表盘和工作流。你可以方便地筛选“缺少法语”或“需要审核”，分配负责人并计算进度。缺点是导出重建语言文件需要分组和排序，还需要额外字段记录文件路径和命名空间。

逐文件文档（每个语言文件作为一个 JSON/YAML 文档存储）与仓库结构一一对应，导出更快且容易保持格式一致。但除非你也维护键、状态和元数据的索引，否则搜索和过滤会变困难。

许多团队采用混合方案：以逐键一行为事实来源，同时生成导出用的文件快照。

版本控制：每个翻译与每次发布的修订

在翻译单元级别（key + locale）保持修订历史。每次变更都应记录：之前的值、新的值、作者、时间戳和备注。这样审核与回滚变得简单。

另外，追踪发布快照：比如“在 v1.8 中到底发布了什么”。快照可以是一个标签，指向各语言中一组一致的已批准修订，避免后续编辑悄悄修改已发布内容。

复数与性别规则

不要把“复数”当成一个布尔值。使用 ICU MessageFormat 或 CLDR 类别（如 one, few, many, other），以免把波兰语或阿拉伯语逼入英文规则。

对于性别和其他变体，把它们建模为同一 key（或消息）的变体而不是零散的独立 key，这样翻译人员能看到完整上下文。

可扩展的搜索与过滤

对 key、源文本、翻译和开发者备注实现全文检索，并配合能反映真实工作的过滤：状态（新/已译/已审）、标签、文件/命名空间 和 缺失/空值。

尽早为这些字段建索引——搜索是人们每天会用数百次的功能。

选择可扩展的架构

本地化管理 Web 应用通常起步简单：上传文件、编辑字符串、再下载。但当你加入多个产品、众多语言、频繁发布和持续自动化（同步、QA、机译、审核）时事情就变复杂。

早期将关注点分离是保持灵活性的最好方式。

一套实用的技术栈

常见且可扩展的架构是 API + Web UI + 后台任务 + 数据库：

• Web UI：翻译编辑器、审核界面与项目设置。
• API：UI、CLI 和集成使用的单一事实来源。
• 后台任务：长时运行的工作（导入/导出、QA 扫描、同步），不应阻塞 UI。
• 数据库：存储项目、键、翻译、历史和权限。

这种分离能让你为重任务增加更多 worker，而无需重写整个应用。

如果你想更快地做出首个可运行版本，像 Koder.ai 这样的低代码平台可以帮助你从结构化规范和聊天迭代中生成 React UI、Go API 和 PostgreSQL 模式，然后当你准备好接管仓库与部署时导出源码。

如何构建 API 结构

让 API 围绕少量核心资源：

• Projects：应用/产品容器。
• Locales：项目启用的语言/地区。
• Keys：稳定标识（例如 checkout.button.pay）。
• Translations：每个 key+locale 的实际文本，以及状态（draft/approved）、作者、时间戳。

设计端点时既要支持人工编辑也要支持自动化。例如，列出 keys 时应接受像“在某语言中缺失”、“自某时起有变更”或“需要审核”之类的过滤器。

你需要的后台任务

把自动化视为异步工作。队列一般处理：

• 导入（解析语言文件、校验、创建/更新键）
• 导出（为发布构建语言包）
• QA 检查（占位符、长度、HTML、禁用词）
• 同步任务（与 Git、CI 或其他系统的拉取/推送）

让任务达到幂等性（可安全重试），并为每个项目记录任务日志，团队就能自助诊断失败。

早期重要的性能细节

即便小团队也能产生很大数据量。为列表（keys、历史、任务）加入分页，缓存常用读取（项目语言统计），并对导入/导出端点与公共 token 应用速率限制。

这些乏味的细节能防止当采用增加时系统在关键时刻变慢。

添加认证角色与权限

如果你的应用存储源字符串与翻译历史，访问控制不是可选项——它能防止误改并让决策可追溯。

选择符合真实工作的角色

一套简单的角色能覆盖大部分团队需求：

• Admin：管理组织设置、语言、集成与用户访问。
• Developer：编辑源字符串、创建键、触发导入/导出。
• Translator：在被分配的语言中编辑翻译。
• Reviewer：批准或拒绝翻译并锁定最终用词。
• Viewer：只读供相关利益人查看。

定义权限（不要只写头衔）

把每个动作视为一个权限，这样便于未来演进。常见规则：

• Edit source：仅 Admin、Developer（防止翻译人员改动含义）。
• Approve：Reviewer（可选地 Admin）以强制明确审核流程。
• Export：Developer/Admin，或如果 Reviewer 负责发布则允许 Reviewer。
• Manage locales：仅 Admin（新增语言会影响工作流与预算）。
• Edit translations：Translator/Reviewer 在被分配的语言与项目范围内。

这种方式既匹配翻译管理，又能对外包/合同工友好。

登录方式：SSO vs 邮箱密码

如果公司已使用 Google Workspace、Azure AD 或 Okta，SSO 能降低密码风险并简化离职处理。邮箱/密码适合小团队——但要强制强密码与重置流程。

会话安全基础

使用安全、短时会话（HTTP-only cookie）、防 CSRF、速率限制，并尽可能启用 2FA。

审计日志以保证问责

记录谁在什么时候改了什么：编辑、批准、语言变更、导出与权限更新。配合“撤销”功能（通过版本历史）以便安全快速回滚（参见 /blog/plan-storage-and-versioning）。

构建核心 UI 屏幕

UI 是本地化工作实际发生的地方，所以优先做好能减少来回沟通并让状态一目了然的屏幕。

1) 项目总览（“控制室”）

从一个能快速回答三个问题的仪表盘开始：什么已完成、什么缺失、什么被阻塞。

按语言显示进度（翻译百分比、审核百分比），并清晰展示“缺失字符串”数量。加入审核队列小组件突出待批准项，以及“最近变更”供审查者快速发现风险性修改。

过滤比图表更重要：语言、产品区、状态、受让人与“自上次发布以来的变更”。

2) 翻译编辑器（快速、有上下文、可审计）

优秀的编辑器是并排显示：左侧源文，右侧目标文，并始终可见上下文。

上下文可包括键、截图文字（如果有）、字符限制和占位符（例如 {name}, %d）。在同一视图中显示历史与评论，这样翻译人员不需要额外的“讨论”界面。

把状态流做成一键完成：Draft → In review → Approved。

3) 批量操作（给经理和负责人用）

本地化工作往往是“很多小改动”。提供批量选择并支持动作：分配给用户/团队、修改状态、为某语言或模块导出/导入。

对批量动作按照角色进行权限限制（参见 /blog/roles-permissions-for-translators）。

4) 无障碍与键盘快捷键

高频翻译人员会长时间待在编辑器中。支持完整键盘导航、可见焦点态与快捷键，例如：

• 下一个/上一个字符串
• 保存并标记“待审核”
• 复制源到目标

同时支持屏幕阅读器与高对比模式——无障碍也会提升整体效率。

创建翻译工作流

本地化管理 Web 应用的成败系于工作流。如果人们不知道下一步该翻译什么、谁负责决定或为什么字符串被阻塞，项目就会延误并质量参差。

分配流：谁在翻译什么及截止时间

从明确的工作单元开始：特定版本中某语言的一组 keys。让项目经理（或负责人）按 语言、文件/模块 和 优先级 分配任务，并可选设定截止日。

把分配在“我的工作”收件箱中展示，回答三个问题：分配了什么？哪些逾期？哪些在等待别人？对大团队来说，加上工作量信号（项数、估计词数、最后活动）能让分配更公平可预期。

审核流：评论、建议、批准与拒绝

搭建一个简单的状态流水线，例如：Untranslated → In progress → Ready for review → Approved。

审核不仅是二元检查。支持内联评论、建议修改和带原因的批准/拒绝。当审查者拒绝时保留历史——不要覆盖原有内容。

这会使翻译审核可审计并减少重复错误。

冲突处理：源变更与“需更新”标记

源文本会变更。变更发生时把现有翻译标记为 Needs update，并显示差异或“变更了什么”的摘要。保留旧翻译作参考，但禁止在未明确决策下重新批准它。

通知：分配与审核请求的邮件/应用内通知

对阻塞进度的事件发送通知：新分配、发起审核、被拒绝、截止日临近，以及影响已批准字符串的源变更。

让通知具备可操作性并带深度链接，例如 /projects/{id}/locales/{locale}/tasks，以便用户一键解决问题。

自动化导入、导出与同步

手工文件操作是项目漂移的根源：翻译人员处理陈旧字符串，开发者忘了拉更新，发布时出现半成品语言。

好的本地化管理 Web 应用应把导入/导出当作可重复的流水线，而不是一次性任务。

构建导入/导出流水线

支持团队实际使用的常见路径：

• 从仓库拉取（GitHub/GitLab/Bitbucket）：按计划或按需抓取语言文件。
• 推回仓库：用更新的翻译发起 PR 而不是直接写入 main。
• 手动上传/下载：对供应商或遗留项目仍然必需。

导出时允许按 项目、分支、语言与状态 过滤（例如“仅导出已批准”），以避免半审阅的字符串泄露到生产。

字符串抽取与稳定键

同步仅在键保持稳定时才有效。早决定字符串如何生成：

• 若使用 可读键（例如 checkout.button.pay_now），保护它们避免意外重命名。
• 若使用 哈希键，保存源字符串与上下文以防更新时静默创建重复项。

应用应检测到源字符串变更但 key 未变的情况，并把翻译标记为 needs review 而不是覆盖它们。

提交与发布的 Webhook

加入 webhook 以实现自动同步：

• main 有新提交 → 导入更新的源字符串。
• 创建发布标签 → 导出“已批准”翻译并发起 PR。

Webhook 应具备幂等性（可安全重试），并产生日志：改了什么、跳过了什么、为什么。

集成提示

如果你在实现这一点，记录一个最简单的端到端设置（仓库访问 + webhook + PR 导出），并在 UI 中链接，例如：/docs/integrations。

添加本地化 QA 检查

本地化 QA 是翻译管理从简单编辑器变成防止生产 bug 的工具的关键。目标是在字符串上生产前发现问题——尤其是只会在某个语言文件中出现的问题。

1) 验证（阻断错误）

先从会破坏 UI 或导致格式化出错的检查开始：

• 缺失或不匹配的占位符（例如源文本有 {count}，但法语缺失，或复数形式不一致）。
• 字符串内的无效 HTML（允许标记时的破损标签或未闭合实体）。
• 对文件格式不做转义的字符（JSON 中的引号、printf 风格字符串中的孤立 %、格式错误的 ICU 消息）。

默认把这些当作“发布阻断”，并给出明确错误信息和指向具体 key 与语言的定位。

2) 一致性检查（软警告）

这些不一定会破坏应用，但会损害质量与品牌一致性：

• 术语表术语：标记未使用或翻译不一致的必用术语。
• 标点、空白与大小写：多余空格、尾随空格、缺失句末标点或引号不匹配。

3) 可视化检查（上下文感知）

文本可能语法上正确但视觉上不合适。为每个 key 提供请求截图上下文的方式（或允许把截图附加到 key），以便审查者验证截断、换行与 UI 中的语气。

4) 报告（发布就绪摘要）

在每次发布前生成每个语言的 QA 摘要：错误、警告、未翻译字符串和主要问题项。

让它易于导出或内部链接（例如 /releases/123/qa），以便团队有单一的“是否发布”视图。

支持术语表、翻译记忆与机器翻译

加入术语表、翻译记忆（TM）和机器翻译（MT）能显著加速本地化——前提是你的应用把它们当作建议和辅助，而不是“可直接发布”的内容。

术语表：每语言的批准词条

术语表是带有每种语言批准翻译的术语列表（产品名、UI 概念、法律短语）。

以 term + locale + approved translation + notes + status 的形式存储条目。

为翻译工作加入术语表支持：

• 在源字符串中高亮术语匹配并建议目标中使用批准术语。
• 当翻译偏离必用术语时发出警告（或根据项目设置阻断）。
• 通过简单规则支持屈折/变体（例如大小写不敏感匹配），避免过度严格的强制。

翻译记忆基础

TM 重用之前批准的翻译。保持简单：

• 用（归一化源文本、上下文 key、locale）做索引。
• 优先显示“已批准”段落；回退到“已审核”或“导入”的结果。
• 显示匹配质量（完全匹配 vs 模糊匹配）与原始上下文，让用户信任建议。

把 TM 当成建议系统：用户可以接受、编辑或拒绝匹配，只有被接受的翻译才应回写到 TM。

将机器翻译作为辅助

MT 对草稿和 backlog 很有用，但不应成为默认最终输出。

让 MT 在项目或任务层面可选，并把 MT 填充的字符串送入正常审核流程。

成本与隐私：由管理员控制

不同团队有不同约束。允许管理员选择供应商（或完全禁用 MT）、设置用量限制并选择发送的数据（例如排除敏感键）。

记录请求以便成本可见与审计，并在 /settings/integrations 中记录选项。

发布并保持可靠

本地化应用不应仅仅“存储翻译”——它应该帮助你安全地发布它们。关键概念是发布（release）：针对某次构建冻结的已批准字符串快照，这样部署内容是可预测且可复现的。

定义“发布”包含的内容

把发布视为不可变的包：

• 语言 + 命名空间/文件 + key + 最终批准文本
• 元数据：批准状态、审查者、时间戳、源字符串哈希
• 可选：构建号、git 提交与应用版本

这能让你回答：“在 v2.8.1 中我们到底为 fr-FR 发布了什么？”而不必猜测。

支持环境（staging 与 production）

大多数团队希望先在用户看见之前先验证翻译。按环境建模导出：

• Staging 导出：包含新批准的字符串以及可能的“候选”翻译供预览
• Production 导出：仅包含完全批准的内容，且绑定到发布 ID

让导出端点明确（例如：/api/exports/production?release=123），以防止未审阅文本意外泄露。

从一开始就设计回滚

回滚在发布不可变时最简单。如果某次发布引入问题（占位符错误、术语错误），你应该能：

• 把应用回滚到之前的发布导出
• 重新打开有问题的字符串并修复，然后切新的发布

避免“在生产中就地编辑”——它会破坏审计记录并让事故难以分析。

值得注意的是，这种“快照 + 回滚”的思路与现代构建平台的工作方式相契合。例如 Koder.ai 将快照与回滚作为首要工作流，这对你设计不可变的本地化发布有启发意义。

发布后的检查与监控

部署后运行一份运营检查清单：

• 所有语言的导出成功；无缺失文件
• 对主要用户路径做基本运行时冒烟测试
• 监控翻译错误信号（缺失键、占位符不匹配、突然的回退激增）

在 UI 中展示发布历史时，包含一个“与上次发布的 diff”视图，让团队能快速发现高风险变更。

安全、分析与后续步骤

安全与可见性是有用的本地化工具与团队信任工具的差别。一旦工作流运行稳定，就把它锁住并开始度量。

要内建的安全基础

默认遵循最小权限：翻译人员不应能修改项目设置，审查者不应有账单或管理员导出的权限。把角色显式化并可审计。

安全存储密钥。把数据库凭据、webhook 签名密钥和第三方 token 放在秘密管理器或加密环境变量中——不要放在仓库。按计划或人员变动时轮换密钥。

备份不是可选项。对数据库与对象存储（语言文件、附件）做自动备份、测试恢复并定义保留策略——“恢复不了的备份”只是浪费空间。

PII 考量（尤其是用户生成的字符串）

若字符串可能包含用户内容（工单、姓名、地址），尽量不要把它们存到翻译系统。优先使用占位符或引用，并在日志中剥离敏感值。

若必须处理此类文本，定义保留规则与访问限制。

真正有用的基础分析

跟踪反映工作流健康的少量指标：

• 吞吐量：每天/每周翻译的字符串数
• 审核时间：从“已翻译”到“已批准”的平均时长
• 频繁变更的 key：识别高变更率的 UI 区域以便重构

一个简单的仪表盘外加 CSV 导出就足够起步。

扩展能力的后续步骤

一旦基础稳定，可以考虑：

• 为推/拉与状态检查提供开发者 CLI
• 一个上下文内编辑器以在 UI 中预览字符串
• 提供 API key 以集成 CI、GitHub/GitLab、Slack 等

如果你打算把它作为产品对外提供，加入清晰的升级路径和号召性用语（见 /pricing）。

如果你的直接目标是用真实用户快速验证工作流，也可以在 Koder.ai 上原型化 MVP：在 planning 模式下描述角色、状态流和导入/导出格式，通过聊天迭代 React UI 与 Go API，然后在准备好进入生产加固时导出代码库。