You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/USER_COPY_CATALOG.md

11 KiB

用户界面文案目录

Virt Cloud 的用户界面文案使用“源码中文合同 + 管理员目标语言译文”模型。源码只保存简体中文安全基线、稳定语义键和渲染元数据;英文及其他目标语言译文不得进入仓库,必须由管理员在后台录入、发布和回滚。

双平面架构

系统把编辑与用户请求严格分开:

  1. 管理平面使用数据库表 ui_copy_locales、ui_copy_entries、ui_copy_drafts、ui_copy_publications 和 ui_copy_revision_items。它负责同步源码合同、保存管理员草稿、校验参数、记录不可变发布历史和执行回滚。
  2. 运行平面只读取 web/storage/framework/user-copy/current.json 及其指向的 generations/<generation>/ 不可变 PHP/JSON 文件。普通用户请求不会查询上述五张翻译表,也不会在文件缺失或损坏时临时回查数据库。

发布器先完整写入并校验一个不可变 generation,再原子切换 current.json。写入或校验失败时旧指针继续生效;回滚只把对应语言的指针切回已验证的历史 generation。PHP 模板和浏览器运行时从同一份 generation 读取,因此不存在服务器端和浏览器端各自维护一套译文的问题。

目标语言中缺少、过期或与当前源码/参数合同不兼容的词条,会逐词回退到当前中文源码基线。回退不读取数据库。已发布译文只有在 source_hash 与 placeholder_hash 仍兼容时才会继续使用。

源码合同

入口为 web/resources/user-copy/manifest.php,页面词条按功能拆分在 web/resources/user-copy/entries/*.entries.php。每条词条必须声明:

  • 静态小写语义键,例如 instance.settings.hostname.help;禁止运行时拼接键,也禁止 .dynamic.h<hash> 形式的临时哈希键。
  • scope、page、文案种类、中文基线、格式、参数合同、风险级别和是否允许隐藏。
  • 需要插值时使用 ICU 格式并完整声明参数;译文必须保持参数合同。
  • 支付、删除、重装、数据丢失、效果未知等关键文案必须可见,不能被目标语言草稿隐藏。
  • Toast 的语义级别由源码合同决定。译文管理员只能修改内容,不能把错误或警告改成成功提示。

条目文件返回带 key 字段的列表,而不是以 key 作为 PHP 数组下标。这样加载合同可以发现重复键,避免 PHP 在解析关联数组时静默覆盖。校验后目录按键排序,源码排列顺序不会改变摘要。

页面范围

当前 Manifest 明确登记以下用户页面及公共界面:

分组 页面键
公共与认证 public.home、public.error、auth.login、auth.register、auth.password
法律页面 legal.terms、legal.privacy
云资源 cloud.instances、cloud.deploy、cloud.detail、cloud.reinstall、cloud.backups、cloud.snapshots、cloud.traffic、cloud.vpcs、cloud.isos、cloud.keys
账单 cloud.invoices、cloud.invoice_detail、user.recharge
账户与支持 user.account、user.invite、user.tickets、user.tasks、user.announcements

common scope 提供导航、通用对话框、通用请求错误、Toast 标题等跨页内容;页面只能加载 Manifest 为该页面登记的 scope。UserCopyPageResolver 负责非 Cloud 用户路由的页面映射,Cloud 页面在控制器绑定时显式指定页面键。

当前公共语言选择支持 zh-CN 与 en:优先使用 ?lang=,其次使用持久 Cookie,最后解析浏览器 Accept-Language。源码没有英文兜底;尚未发布英文译文的条目按上述规则显示中文基线。

运行范围与编辑归属

scope/page 与 editor_surface/editor_group 是两套正交分类,不能互相替代:

  • 运行范围决定普通用户请求可以加载哪些词条,继续由 scope、Manifest 页面键和 UserCopyPageResolver 控制。
  • 编辑归属决定词条从哪个作者界面维护。page 归属当前页面正文;shared 归属导航、页眉、页脚等公共框架;dialog、feedback、task、accessibility 归入后台动态文案中心。

因此,用户页面内的超级管理员编辑器通过服务端分页和搜索显示当前 Manifest 页面登记的完整 page 文案目录;当前 DOM 已绑定的词条额外提供“定位文案”,未绑定或条件状态下尚未渲染的词条仍可编辑。shared 公共框架继续只显示当前 DOM 已绑定且属于该页面允许分组的词条。编辑器不能扩大运行时 scope,也不能直接发布。管理员后台只管理弹窗、反馈、任务和无障碍等动态文案。所有入口最终写入同一草稿账本,并由同一发布事务生成不可变目录。

管理员工作流

超级管理员通过“管理员后台 → 用户界面译文”完成以下操作:

  1. 同步源码词条:把当前 Manifest 投影到管理账本;源码删除的条目标记为孤立,中文基线或参数合同变化会使不兼容草稿变为 stale。
  2. 编辑草稿:后台动态文案中心或用户页面内编辑器保存草稿;保存时校验 UTF-8、长度、ICU 参数、可见性和乐观版本。浏览器内未保存输入按“语言 + 稳定键”缓存,翻页、搜索和切换编辑分组不会清空;切换语言或离开页面前必须明确确认。
  3. 安全预览:预览使用受限 iframe,不执行目标译文中的脚本。
  4. 发布目标语言:把有效草稿和兼容的历史译文编译为新的不可变目录,并原子激活。
  5. 发布历史与回滚:历史发布保留完整词条快照;回滚只允许切换到已经通过完整性校验且属于同一语言的 generation。

后台显示的目录覆盖率只描述当前编辑通道与分组;publication_readiness 则始终核对该目标语言的全部活动草稿,不受当前搜索、类型、状态或分页条件影响。任意 invalid、stale 或 pending 草稿都会阻断发布;正式发布事务仍执行最终完整性校验。

目录读取接口保留 page 作为 Manifest 页面键,并使用独立的 catalog_page 与 per_page 分页;per_page 默认为 50、最大 100。q 搜索稳定键和中文源文案,surface 与 state 执行服务端筛选,响应返回稳定键排序后的 pagination。groups、覆盖率与发布就绪度均在分页和筛选前计算。

管理员目录和页面内编辑器只会取消 GET 读取:前端同时使用 AbortController、请求序号及筛选/语言/标签签名拒绝陈旧响应。保存、发布、同步和回滚等 mutation 不会因界面切换被取消,也不会自动重放;结果不确定时必须人工核对。

数据库是编辑和审计账本,不是用户请求的运行时依赖。管理员页面或数据库临时不可用不会影响已经发布的用户界面目录。

模板与浏览器运行时

Smarty 模板使用 {user_copy key='...'};浏览器代码使用 VenixUserCopy.text(key, parameters),并通过同一运行时提供的 number、currency、date 和 bytes 格式化数值。页面 Bootstrap 只包含当前页面 scope 所需的消息和元数据。

web/tests/UserCopyCompleteCoverageTest.php 是用户前端文件所有权清单和最终覆盖门禁:

  • 显式列出所有非管理员 Venix 模板,包括根级落地页、错误页、认证、Cloud、账户、法律页和共享组件;新增或删除模板必须同时更新清单。
  • 显式列出所有用户专属浏览器 JS;web/public/cloud/ 和 web/public/theme/venix/js/ 中每个 JS 都必须被分类为用户、管理员、基础设施、vendor 或明确未使用。
  • 管理员 JS/CSS、vendor 文件、上传哈希 Worker 和未被用户模板加载的遗留探测脚本不参与用户文案扫描,避免把管理后台文案和协议常量误判为用户译文缺口。

门禁拒绝:

  • 未登记的可见中文,以及模板中未登记的可见英文文本或可见英文属性;
  • 直接写入字面量的 Toast/Confirm 文案;
  • 固定 zh-CN 的浏览器日期或数字格式;
  • 直接读取或展示后端 message、detail、msg、errmsg、error;
  • .dynamic.h<hash> 临时哈希键和旧 $language == 'true' 分支;
  • 未分类的新模板、新 Cloud JS 或新 Venix JS。

允许排除的内容只有四类,而且标记必须与代码同一行并附带非空原因:

// user-copy: allow technical-constant non-rendered protocol token
// user-copy: allow technical-regex backend classifier never rendered
// user-copy: allow test-fixture scanner rejection sample
// user-copy: allow admin-compatibility shared admin fallback

technical-constant 只用于不渲染的协议、单位或机器标识;technical-regex 只用于对后端技术错误进行分类且匹配内容绝不直接显示;test-fixture 只允许出现在测试样本;admin-compatibility 只允许用于同一资产同时被管理员页面加载、管理员尚无用户目录 Bootstrap 的兼容 fallback,而且用户路径仍必须优先从目录读取。普通用户专属资产不能使用 admin-compatibility。实际用户文案、后端错误原文和其他临时 fallback 都不能借标记绕过目录。任意其他类别、缺少原因或单独一行的标记都会被门禁拒绝。

部署与发布

  1. 同时发布 PHP、模板、浏览器资产和 Manifest;不得只发布其中一部分。
  2. 全新环境从当前 web/sql/ss.sql 创建数据库。既有环境必须先备份,再用经审核的一次性增量迁移创建上述五张 ui_copy_* 表和约束;不得在非空数据库运行 php xcat cloudInit 冒充升级。
  3. 确认 PHP 运行用户可以创建并原子重命名 web/storage/framework/user-copy/ 下的文件和目录;不要预先手工编写 current.json。
  4. 重启/重载承载 PHP 的长期进程,使其加载同一版本代码;按项目共享资源版本发布静态文件。
  5. 以超级管理员进入“用户界面译文”,先执行“同步源码词条”,确认投影完整后录入英文草稿。
  6. 发布目标语言,确认 current.json 已指向新 generation,并分别验收 Smarty 页面、浏览器动态提示、语言切换和中文缺词回退。
  7. 发布后运行下列合同测试;覆盖门禁必须为零违规才能视为迁移完成:
php web/tests/UserCopyManifestContractTest.php
php web/tests/UserCopyCoverageScannerTest.php
php web/tests/UserCopyCompleteCoverageTest.php

用户请求只依赖源码中文基线和已发布文件,因此翻译数据库停机验收应保持页面可读;删除或篡改当前 generation 的测试只能在隔离环境执行,并应验证安全回退而不是数据库回查。