Translate（翻译与适配）

Translate 把外部输入源转换成框架内部的数据包与资源包。框架自身不识别任何外部格式；格式名、识别特征与映射全部来自规则条目与 codec 单元，仓库内只有自造夹具。

顶部信息表

项	内容
契约版本	`translate@1`
当前状态	已完成
源码目录	`src/core/translate`
页面定位	面向翻译器与规则作者，说明识别、作业、归档解压、隔离运行与产物写出

职责

负责：

按规则识别输入源的格式与入口；
把 ZIP 展开为可逐项读取的目录来源；
在隔离环境中运行 codec，执行剧本与资源转译；
把产物逐包写成数据包与资源包；
广播作业进度与失败信息。

不负责：

具体外部格式的解析与映射；这部分由 codec 单元提供；
产物的自动装载与信任授予；写出不等于准入；
资源在运行期的读取、缓存与解码，见 Asset；
译文的排版与语言切换，见 Text。

对外接口

名称与 policy 以 src/core/translate/contract.ts 为准。

名称	类别	policy	说明
`translate:detect`	服务	`trusted`	识别输入源可能匹配的规则
`translate:archive`	服务	`trusted`	把 ZIP 展开为目录来源
`translate:run`	服务	`trusted`	执行一次翻译作业并写出产物
`translate:rules`	服务 + registry	服务 `trusted`，条目缺省 `public`	规则查询与登记
`translate:resolve-rule`	机制插槽	`trusted`	调整交给 codec 的规则 JSON
`translate:resolve-pipeline`	机制插槽	`trusted`	选择作业使用的 codec 实现
`translate:on-progress`	通知	—	作业阶段进度
`translate:on-failed`	通知	—	作业失败信息
`translate:codec@1`	实现位（multi）	`public`	强制隔离运行，只能由装载器代理登记
`translate:emitter@1`	实现位（single）	`trusted`	默认 `directory`，写标准目录树

服务方法

detect(input)：input = { source, label? }，返回 [{ rule, format, confidence }]。
run(job)：job = { input, rule, codec?, budget?, signal? }，返回 { job, packs: [{ id, kind, source }] }。
archive(input, options?)：返回 { source, close(), ended }，用于逐项读取归档内容。

规则条目

规则 schema 为 rule-1：

json

{
  "format": "格式名",
  "entry": "输入源内的入口路径",
  "detect": { "paths": ["用于识别的路径特征"] },
  "rule": {}
}

rule 只接受 JSON，不接受可执行代码。条目缺省为 public；同名服务本身为 trusted，服务保护与条目数据覆盖分别判定。

关键语义

识别

确认引用的规则存在。
确认规则声明的入口在输入源内。
按 detect.paths 计算置信度：命中数 ÷ 总数；零命中不列出。

置信度不是安全判定，只是候选排序。低置信度结果应由调用方再次确认，不能直接开始作业。

作业顺序

识别核验：规则存在、入口在输入内。
选择翻译器：只在清单声明支持该格式的候选中选；翻译器须已获准读取原始字节与本次输入目录。
隔离运行：主 realm 代该单元读取本次输入；在专用 Worker 中执行 codec。
逐包写出：单包提交，不含跨包事务。

预算默认值为墙钟 30 分钟、输入 1 GiB、输出 1 GiB；可调高到 240 分钟与 8 GiB。超限即终止并销毁隔离环境；失败通知中的 code 为 TRANSLATE_BUDGET_EXCEEDED。

进度通知的 stage 取 detect、decode、copy、emit，载荷为 { job, stage, done, total }。失败通知载荷为 { job, reason, code?, message, usage, budget }。

归档解压

只支持存储与 deflate；ZIP64、分卷与加密条目明确报不支持。
中央目录上限 64 MiB，超出即拒绝，不先读入。
每次读取按「本地文件头与压缩数据的读入量」和「解压后的字节量」取较大值计入输入预算，再读取；单个条目的压缩数据与解压结果都不得超过 256 MiB，超限条目照常列出，读到时才拒绝。
单个条目解压比上限为 100 倍。
读取逐个进行，同一时刻只有一个条目的字节在途；等待中的读取最多 64 个，超过后只拒绝该次请求，会话仍可继续。
解压由仓库内与具体输入源无关的 Rust crate 编译为 WASM，只在隔离环境的专用 Worker 中实例化；主页面不放行 WASM 即时编译。
打开失败时等隔离环境撤完才报错。

目录输入在列举阶段同时限制文件数、目录数、单文件大小、单包总量与路径深度。网页选择目录只保留上限加一项供下游明确报超限，拖入目录还限制单次目录读取量；不会把整个浏览器 FileList 一次展开。网页与 Tauri 写出器在打开期累计单文件、文件数与总量，Tauri 创建产物文件时沿已核对的暂存目录句柄逐级建目录，拒绝跟随符号链接或 Windows 重解析点。

产物写出

默认 emitter 为 directory，经 host:backend@1 的 createPack() 写标准目录树。
网页宿主只有在 OPFS 与 Web Locks 都可用时提供写出入口；缺少任一能力时明确报告当前宿主不支持写出产物，读取与装载仍可用。
OPFS 完成标记先核对不超过 4 KiB；已完成产物最多列出 10,000 个。创建产物时先持有本产物的锁，再建立目录；初始化失败先清理目录再释放锁。没有完成标记的目录，只有在能确定创建时刻、超过 24 小时且确认没有写入者时才回收；无法确定创建时刻的目录保留。
Tauri 先写暂存目录，再原子改名到正式包目录；暂存同时最多 16 个、合计 4 GiB，空闲 1 小时回收，写入前预留字节，提交与取消的清理不把磁盘 I/O 放在全局锁内。
写出不授予信任，也不自动装载；产物须由用户逐个选择装载，并照常经过准入判定。
未签名产物在装载时需要用户批准。

外壳集成

内置外壳的「离线翻译」看板提供：

选择或拖入目录／ZIP。
识别；置信度低于 100% 时再次确认。
显示四个工序槽位。
产物逐个装载。

超预算时显示三项对照与调高表单。写出失败可只重试写出；拒绝值带 stage、retryEmit() 与 discard()。写出途中取消即停止，不再写下一个包；写出与重试同时只有一个在进行，重试进行中再点一次会被拒绝。

Tauri 窗口关闭原生拖放拦截，拖入内容按浏览器 File 对象读取，不出现本地路径。

当前实现范围

已完成：四个服务、规则 registry 与查询、装载器代理登记、隔离运行、ZIP 归档解压、目录 emitter、进度与失败通知、内置外壳的离线翻译看板。
已完成：翻译产物的暂存与提交策略；网页与 Tauri 各自使用对应宿主后端。
按设计不自动装载产物，这不是未实现项；装载仍由用户发起并经过 guard。
未实现：仓库内不内置任何具体格式的 codec；格式支持范围完全取决于已装载的 codec 单元。

Translate（翻译与适配） ​

顶部信息表 ​

职责 ​

对外接口 ​

服务方法 ​

规则条目 ​

关键语义 ​

识别 ​

作业顺序 ​

归档解压 ​

产物写出 ​

外壳集成 ​

当前实现范围 ​

相关链接 ​