# mtran ROS2 英译中服务

`mtran` 是一个 ROS2 Humble C++ 功能包。它提供同步服务
`/translate_en_to_zh`，请求中放入一句英语，响应中返回简体中文译文。

```text
ROS2 Service 请求
        |
        v
mtran_bridge_node (C++ / libcurl)
        |
        v
常驻 MTranServer sidecar (Bergamot WASM / en_zh-Hans 模型)
```

MTranServer 随 `ros2 launch` 启动并保持常驻。模型只在启动阶段预热，不会在每次
Service 调用时临时启动或重新加载。本包不提供话题接口、批量翻译、多语言选择、
HTML 翻译或自动语言检测。

## 1. 环境前提

- Ubuntu 22.04
- ROS2 Humble，且由使用者提前安装
- CPU 架构为 `x86_64` 或 `aarch64`
- 首次准备阶段可访问 apt、npm registry 和 Mozilla 模型站点
- 建议预留约 1.5 GB 临时构建空间

`dependencies/auto_install.sh` 只安装非 ROS 依赖、构建 MTranServer、下载并校验
英译中模型。**脚本不会安装 ROS2，也不会运行 `colcon build`。** ROS2 和 colcon
构建由工作区使用者负责。

## 2. 放入 ROS2 工作区

目标目录必须是：

```text
smart-healthcare-2026/src/mtran
```

在当前项目中，功能包已经位于以下目录：

```bash
cd ~/smart-healthcare-2026/src/mtran
```

复制完成后，当前目录中应直接存在 `package.xml` 和 `CMakeLists.txt`，不能再套一层
`src/mtran`。

## 3. 准备依赖、sidecar 和模型

先加载日常终端环境，再执行：

```bash
source ~/.bashrc
cd ~/smart-healthcare-2026/src/mtran/dependencies
./auto_install.sh
```

脚本会请求 `sudo` 安装非 ROS apt 包，在 `dependencies/tools` 安装固定版本 Bun，
从 `vendor/mtranserver` 构建当前 CPU 可运行的 sidecar，并只准备
`en -> zh-Hans` 模型。成功结尾类似：

```text
Preparation complete.
Next: cd .../smart-healthcare-2026 && colcon build --packages-select mtran
Then: source install/setup.bash && ros2 launch mtran translator.launch.py
```

## 4. 检查准备结果

返回 `smart-healthcare-2026/src/mtran` 执行：

```bash
cd ..
file runtime/bin/mtranserver
test -s runtime/config/records.json
ls -lh models/en_zh-Hans
python3 dependencies/verify_runtime_data.py \
  --records runtime/config/records.json \
  --model-dir models/en_zh-Hans
```

应存在以下生成物：

```text
runtime/bin/mtranserver
runtime/config/records.json
models/en_zh-Hans/model.enzh.intgemm.alphas.bin
models/en_zh-Hans/lex.50.50.enzh.s2t.bin
models/en_zh-Hans/srcvocab.enzh.spm
models/en_zh-Hans/trgvocab.enzh.spm
```

校验器会根据 `records.json` 中的 `decompressedHash` 和 `decompressedSize` 验证四个
模型文件。校验失败时不要继续构建，重新运行准备脚本。

## 5. 构建 ROS2 包

从工作区根目录 `smart-healthcare-2026` 执行，而不是从包目录执行：

```bash
source ~/.bashrc
PYTHONNOUSERSITE=1 colcon build --packages-select mtran
```

成功时应看到：

```text
Finished <<< mtran
Summary: 1 package finished
```

CMake 不会联网、安装依赖或调用 Bun。它只检查第 4 节的准备产物，然后把 sidecar、
模型和 `records.json` 复制到 ROS2 install space。

## 6. 启动

从 `smart-healthcare-2026` 执行：

```bash
source ~/.bashrc
source install/setup.bash
PYTHONNOUSERSITE=1 ros2 launch mtran translator.launch.py
```

launch 同时启动 MTranServer 和 `mtran_bridge_node`。节点会等待 sidecar 健康检查成功，
再执行一次内部英译中预热；只有预热完成后才发布 `/translate_en_to_zh`。日志中应出现：

```text
MTranServer is healthy and the en-to-zh-Hans model is warm
```

## 7. 调用服务

保留启动终端，在第二个终端中从 `smart-healthcare-2026` 执行：

```bash
source ~/.bashrc
source install/setup.bash
ros2 service call /translate_en_to_zh \
  mtran/srv/TranslateEnglishToChinese \
  "{text: 'The robot has completed the inspection.'}"
```

成功响应类似：

```text
mtran.srv.TranslateEnglishToChinese_Response(
  success=True,
  translation='机器人已完成检查。',
  error=''
)
```

## 8. Service 字段和错误码

接口定义：

```srv
string text
---
bool success
string translation
string error
```

- `text`：非空英语普通文本，最多 512 个 UTF-8 字符。
- `success`：翻译成功时为 `true`。
- `translation`：成功时为简体中文；失败时始终为空。
- `error`：成功时为空，失败时为下列稳定错误码之一。

| 错误码 | 含义 |
| --- | --- |
| `INVALID_INPUT` | 输入为空或仅含空白。 |
| `INPUT_TOO_LONG` | 输入超过 512 个字符。 |
| `NOT_READY` | sidecar 未就绪、连接中断或模型正在重新预热。 |
| `TIMEOUT` | 单次翻译超过 30 秒。 |
| `UPSTREAM_ERROR` | HTTP 传输或 MTranServer 状态异常。 |
| `INVALID_RESPONSE` | sidecar 返回的 JSON 缺少字符串 `result`。 |

节点使用单线程 executor，同一时刻串行处理请求，不考虑多句批处理。

## 9. 常驻预热和离线运行

launch 固定向 sidecar 设置：

```text
MT_HOST=127.0.0.1
MT_PORT=8989
MT_ENABLE_UI=false
MT_OFFLINE=true
MT_CHECK_UPDATE=false
MT_WORKER_IDLE_TIMEOUT=86400
MT_CACHE_SIZE=100
```

准备和 `colcon build` 完成后，运行阶段不需要网络。模型 worker 的空闲时间为 24 小时，
桥接节点每 12 小时发送一次内部保温翻译。sidecar 异常退出时 launch 会在 2 秒后重启；
恢复期间服务返回 `NOT_READY`，健康检查和重新预热成功后自动恢复。

## 10. x86_64 和 ARM64

C++ 源码和模型数据不区分 CPU 架构。`auto_install.sh` 在运行机器上本机构建 sidecar：

- `uname -m` 为 `x86_64` 时生成 x86-64 ELF。
- `uname -m` 为 `aarch64` 时生成 ARM64 ELF。

推荐把同一个包目录复制到 ARM64 Ubuntu 22.04 目标机后，在目标机执行准备脚本和
`colcon build`。本包不提供 x86_64 主机到 aarch64 的交叉构建流程。已经下载的
`records.json` 和模型可以跨架构复制，但 `runtime/bin/mtranserver` 必须与目标机架构
匹配；脚本检测到不匹配时会重新构建。

## 11. 重复安装和清理

准备脚本可重复执行。它会复用以下有效产物：

- 版本正确的工作区 Bun
- 架构正确的 sidecar
- 哈希和大小正确的四个模型文件

只重新构建 sidecar，从 `smart-healthcare-2026/src/mtran/dependencies` 执行：

```bash
rm -f ../runtime/bin/mtranserver
rm -rf ../.build/mtranserver
./auto_install.sh
```

完全重新准备，从同一目录执行：

```bash
rm -rf tools ../.build ../runtime/config ../models/en_zh-Hans
rm -f ../runtime/bin/mtranserver
./auto_install.sh
```

清理 ROS2 构建结果，从 `smart-healthcare-2026` 执行：

```bash
rm -rf build/mtran install/mtran log
colcon build --packages-select mtran
```

## 12. 故障排查

### 提示缺少 ROS2 Humble

脚本不会安装 ROS2。确认 `/opt/ros/humble` 存在，并安装错误信息列出的
`ros-humble-*` 包。然后重新执行准备脚本。

### apt 安装失败

检查 Ubuntu 软件源、代理、DNS 和 `sudo` 权限。apt 成功后可直接重复运行脚本，
已完成的本地步骤会被复用。

### Bun 或 npm registry 失败

检查到 `https://registry.npmjs.org/` 的网络连接。工具安装位置是
`dependencies/tools`；删除该目录后重跑脚本可强制重装 Bun 1.3.14。

### 模型缺失或哈希不匹配

从包根运行第 4 节的 `verify_runtime_data.py`。确认 Mozilla records 与附件 CDN 可访问，
然后删除 `runtime/config` 和 `models/en_zh-Hans` 并重跑准备脚本。脚本只会把完整校验
后的临时下载移动到最终位置。

### 端口 8989 被占用

检查占用者：

```bash
ss -ltnp | grep ':8989'
```

停止冲突进程，或为 launch 同时覆盖 `port`，并确保没有其他节点仍使用旧端口：

```bash
ros2 launch mtran translator.launch.py port:=8990
```

### sidecar 重启后暂时返回 `NOT_READY`

这是恢复阶段的预期行为。等待日志再次出现模型已预热信息后重试；不要为每次请求
手工启动新的 sidecar。

### 找不到 `/translate_en_to_zh`

服务只在健康检查和首次预热成功后创建。先查看 launch 终端日志，再执行：

```bash
ros2 service list | grep translate_en_to_zh
ros2 service type /translate_en_to_zh
```

还要确认调用终端已经 source `/opt/ros/humble/setup.bash` 和当前工作区
`install/setup.bash`。

### Python 用户目录包冲突

若 colcon 或 launch 报告用户目录中的 `setuptools`、`packaging` 版本冲突，在命令前
保留 `PYTHONNOUSERSITE=1`，使 ROS2 Humble 使用 Ubuntu 系统 Python 包。

## 13. 维护者目录参考

```text
mtran/
├── CMakeLists.txt                  ROS2 构建、准备检查和安装映射
├── package.xml                    包元数据和 ROS 依赖
├── dependencies/
│   ├── auto_install.sh            唯一联网准备入口
│   ├── dependencies.txt           完整依赖和下载来源清单
│   ├── verify_runtime_data.py     records/模型完整性校验
│   └── tools/                     工作区 Bun 和缓存（生成）
├── vendor/mtranserver/            固定提交 f5672a9 的上游源码
├── .build/mtranserver/            sidecar 构建目录（生成）
├── runtime/bin/mtranserver        本机 sidecar（生成）
├── runtime/config/records.json    Mozilla 模型索引（生成）
├── models/en_zh-Hans/             四个英译中模型文件（生成）
├── include/mtran/                 C++ 头文件
├── src/                           C++ 实现
├── srv/                           ROS2 Service 定义
├── launch/                        sidecar 与桥接节点启动文件
├── config/                        ROS2 参数
└── test/                          C++、shell 和 Python 测试
```

依赖版本、来源和生成/提交边界以 `dependencies/dependencies.txt` 为准。