🎓 武汉一步汽车专用版
写管用平台
快速上手指南
本手册面向武汉一步汽车团队，帮助您高效上手"写管用"动态发布平台， 掌握从 DITA 手册创建、编辑、翻译到发布的完整工作流。 以 UBTECH 机器人产品手册为实操示例，覆盖中文版编写与多语言翻译全流程。
🌏 第一章
01平台概览与核心工作流
1.1 "写管用"是什么？
"写管用"（Write-Manage-Use）是镭内容出色中心自主研发的内容管理平台，覆盖企业内容创作、管理、分发到多终端交付的全链路。平台核心能力包括：
写 — 内容创作
基于 DITA 标准结构化编写，支持 Oxygen XML Editor 进行 Topic 级模块化创作，实现内容一次编写、多处复用。
管 — 版本管理
基于 GitLab 实现手册的版本控制、分支管理和协同编辑，支持条件发布和受众差异化内容输出。
用 — 多终端发布
通过写管用条件发布系统，一键生成 HTML5、PDF、DOCX 等多种格式的交付物，支持多语言同步输出。
1.2 完整工作流全景
以下是平台的核心工作流程，从创建项目到最终发布交付物：
🔨 规划与新建项目
基于 Master Repo 模板创建主仓库
📚 规划与新建 Map
创建目录结构（concepts/tasks/reference）
▼
✍ 新建 Topic（中文版）
在 Oxygen 中编写 DITA 主题
📤 提交 Repo
Stage → Commit → Push
📝 更新 Topic
版本迭代，v1.0 → v1.1
▼
🌐 新建多语言 Repo
基于 l10n 模板创建翻译仓库
🌎 新建多语言分支
如 EN、JA、FR 等语言分支
▼
🖧 XLIFF 打包翻译
导出 XLIFF → 提交 AI 创新翻译平台 → 回写
🤖 Oxygen AI 翻译
反思翻译/术语推荐/STE 检查
▼
✅ 构建条件 → 选择 Map
在写管用平台配置发布参数
🎉 发布交付物
HTML5 / PDF / DOCX 输出
给武汉一步汽车团队的建议
建议先完成中文版编写（第 3 章）掌握 DITA 结构，再进入翻译流程（第 5 章）学习 XLIFF 和 AI 辅助翻译，最后通过条件发布（第 4 章）查看多语言输出效果。整个流程大约需要 2-3 次实操即可熟练掌握。
建议先完成中文版编写（第 3 章）掌握 DITA 结构，再进入翻译流程（第 5 章）学习 XLIFF 和 AI 辅助翻译，最后通过条件发布（第 4 章）查看多语言输出效果。整个流程大约需要 2-3 次实操即可熟练掌握。
🗃 第二章
02GitLab 仓库管理
2.1 访问信息
| 项目 | 地址 | 说明 |
|---|---|---|
| 核心 Master Repo | ray/bistu-edu | 包含 UBTECH 机器人 + 两个飞行器产品线的 DITA 手册 |
| 本地化翻译 Repo | jeffrey/bistu-edu-l10n | 大模型翻译流程和多语言分支管理 |
| 登录账号 | 用户名 Jeffrey / 密码 vGk7sXj6LNQxWG7 |
|
| Personal Access Token | glpat-i8TJemxAD1PokXoIheEJ6G86MQp1OjcH.01.0w1f6xhdb |
|
重要：认证方式必须使用 HTTPS + PAT
公司 Windows 环境下 JGit 与部分 OpenSSH 版本存在
公司 Windows 环境下 JGit 与部分 OpenSSH 版本存在
rsa-sha2-256/512 算法不兼容问题，会导致 push/pull 随机失败。请使用 HTTPS + Personal Access Token 进行认证，不要用 SSH。
2.2 Git 基础工作流
协同工作流：
远程仓库(GitLab) --clone--> 本地仓库
本地修改 → Stage(暂存) → Commit(提交) → Push(推送)
远程有新内容 → Pull(拉取合并到本地)
2.3 在 Oxygen 中操作 Git
| 动作 | Oxygen 操作路径 |
|---|---|
| Clone 仓库 | Window > Show View > Git Staging → 齿轮图标 → Clone Repository |
| 查看改动 | Git Staging 视图自动显示 Unstaged / Staged 文件 |
| Stage（暂存） | 将改动文件从 Unstaged 拖到 Staged，或点文件旁 + |
| Commit（提交） | 填写 Commit Message → Commit 按钮 |
| Push（推送） | Push 按钮（顶部工具栏或 Git Staging 视图） |
| Pull（拉取） | Pull 按钮，开始工作前务必先 Pull |
| 切换分支 | 右下角分支名 → 下拉选择 / 新建分支 |
2.4 分支命名与版本管理
# 命名规范：release/<产品简称>-<语言>-v<版本号>
git checkout main
git pull origin main
git checkout -b release/ubtech-zh-v1.1
# 版本迭代完成后打 Tag
git checkout main
git pull origin main
git tag -a ubtech-zh-v1.1 -m "UBTECH Chinese Manual v1.1 release"
git push origin ubtech-zh-v1.1
2.5 Commit Message 规范
# 格式：[模块/topic名] 简述改动内容
[c_battery_charging] 更正充电时长参数，2h → 2.5h
[r_troubleshooting] 新增第18条故障排除项
[c_servo_distribution] 更新16个舵机编号对应表
常见踩坑提醒
❌ 忘记 Pull 就开始改 → 容易产生冲突。原则：开工前必 Pull，提交前必 Pull 一次再 Push
❌ 直接用 SSH Clone 报算法错误 → 换成 HTTPS + PAT
❌ 中英文版本号误认为必须同步 → 两者可独立管理，但需注明对应源语言版本号
❌ 忘记 Pull 就开始改 → 容易产生冲突。原则：开工前必 Pull，提交前必 Pull 一次再 Push
❌ 直接用 SSH Clone 报算法错误 → 换成 HTTPS + PAT
❌ 中英文版本号误认为必须同步 → 两者可独立管理，但需注明对应源语言版本号
🔧 第三章
03Oxygen XML 编辑器
3.1 安装与授权
- 下载：Oxygen XML Author 官方下载页
- 安装路径建议：
F:\OxygenXMLAuthor28 - 授权：查阅《编辑器授权》文本文件获取授权码
3.2 首次环境配置
- 打开 Oxygen →
Window > Show View > Git Staging，确认 Git 插件已加载 - 配置 DITA-OT：
Preferences > DITA > DITA-OT，确认内置 DITA-OT 版本 - 确认能出三种格式：HTML5 / PDF（Chemistry）/ DOCX
3.3 DITA Topic 创建与编辑
Step 1 — 打开 Ditamap
在 Oxygen 中打开 dita_alpha1pro/alpha1pro_user_guide.ditamap，在 Map 视图里浏览整个手册的层级结构。
Step 2 — 新建 Topic
右键 topics/concepts/ 目录 → New > DITA Topic，选择类型：
| Topic 类型 | 用途 | 前缀约定 |
|---|---|---|
| Concept | 概念说明、背景介绍、原理阐述 | c_ |
| Task | 操作步骤、流程指引、使用教程 | t_ |
| Reference | 参数表格、故障排除、FAQ | r_ |
Step 3 — 编写内容
在 Author 模式下编辑内容。以下是 UBTECH 安全说明 Topic 的示例结构：
<?xml version="1.0" encoding="UTF-8"?>
<concept id="c_safety_intro" xml:lang="zh-CN">
<title>安全说明</title>
<shortdesc>操作 Alpha 1 Pro 机器人的重要安全信息</shortdesc>
<conbody>
<note type="warning">持 Alpha 的背包摘带，避免摔落损坏</note>
<section>
<title>通用安全预防措施</title>
<ul>
<li>运行时与机器人保持安全距离</li>
<li>连续运行不超过1小时以保护伺服寿命</li>
</ul>
</section>
</conbody>
</concept>
Step 4 — 校验与提交
| 校验类型 | 操作 | 目的 |
|---|---|---|
| 单文件校验 | Ctrl+Shift+V 或工具栏 Validate |
校验单个 .dita 文件的 DITA 合规性 |
| Map 完整性检查 | Validate + Check for Completeness | 确认无断链（missing topicref / broken xref） |
| 本地发布预览 | 右键 ditamap → Configure Transformation Scenario | 预览 HTML5 输出效果 |
Step 5 — 提交到 GitLab
# 在 Git Staging 视图中
# 1. 将改动文件拖到 Staged
# 2. 填写 Commit Message
[c_safety_intro_zh] 初始化中文版安全说明topic，复用英文版结构
# 3. Push 到远程
git push origin release/ubtech-zh-v1.0
3.4 Oxygen AI 插件组合
平台集成了四款 AI 辅助插件，大幅提升编写效率：
A. 反思翻译
AI 对已有翻译进行反思性审校，自动识别语义偏差、术语不一致和风格问题，给出改进建议。
B. 内容推荐
基于上下文智能推荐内容片段，帮助作者快速完成相似结构的 topic 编写，减少重复劳动。
C. 术语管理
自动提取和匹配术语库中的标准译法，确保跨 topic 的术语一致性，支持自定义术语表导入。
D. ASD-STE 检查
对照 ASD Simplified Technical English 规范检查文本，确保英文内容的简洁性和可读性达标。
🚀 第四章
04写管用条件发布系统
4.1 系统访问
| 项目 | 信息 |
|---|---|
| 系统地址 | http://58.87.102.99:8080/#/dita-publish |
| 配套手册 | 写管用条件发布系统操作手册（金山文档） |
4.2 发布操作三步走
Step 1 — 构建条件
在发布系统中配置构建条件（Build Condition），包括：
- 目标格式：选择输出格式（HTML5 / PDF / DOCX）
- 受众条件：设置
audience过滤（如 internal / external / expert / novice） - 平台条件：设置
platform过滤（如 windows / mac / mobile） - 产品条件：设置
product过滤（如 alpha1pro / jimu）
条件发布的核心价值：同一套 DITA 源文件，通过不同条件组合，自动生成面向不同受众、不同平台的差异化内容，实现"一次编写，多渠道发布"。
Step 2 — 选择 Repo > Map
在系统中选择要发布的内容源：
| 选择项 | 说明 |
|---|---|
| Repository（仓库） | 选择 GitLab 上的目标仓库（如 bistu-edu） |
| Branch（分支） | 选择要发布的分支（如 main 或 release/ubtech-zh-v1.1） |
| DITA Map | 选择 map 文件（如 dita_alpha1pro/alpha1pro_user_guide.ditamap） |
Step 3 — 发布与下载
点击发布按钮，系统将自动：
- 从 GitLab 拉取指定分支的最新内容
- 调用 DITA-OT 引擎执行条件过滤和格式转换
- 生成带版本号的输出包（如
AVIC_EN_v1.1_html5.zip） - 提供下载链接，同时保留发布历史记录
发布产出物建议存放路径：
releases/UBTECH-ZH/v1.1/{html,pdf,docx}/，不覆盖历史版本，保留完整可追溯的发布记录。4.3 多条件组合示例
以下是为武汉一步汽车翻译项目常用的条件组合：
| 场景 | 条件组合 | 输出 |
|---|---|---|
| 中文版完整手册 | lang=zh, audience=all, format=html5 |
UBTECH 中文版 HTML5 完整手册 |
| 英文版完整手册 | lang=en, audience=all, format=html5 |
UBTECH 英文版 HTML5 完整手册 |
| 快速入门（精简版） | lang=zh, audience=novice, format=pdf |
面向新手的精简版 PDF |
| 专家参考手册 | lang=en, audience=expert, format=docx |
面向技术专家的 DOCX 参考手册 |
🌐 第五章
05翻译流程
平台支持两种翻译路径，翻译团队可根据项目需求灵活选择：
路径一：XLIFF 打包翻译
适合大批量翻译、多译者协作、需术语一致性审核的项目。通过标准化 XLIFF 格式与 AI 创新翻译平台对接。
路径二：Oxygen AI 翻译
适合快速迭代、单译者、AI辅助的场景。在 Oxygen 编辑器内直接完成翻译、审校、提交一体化。
5.1 路径一：XLIFF 打包翻译流程
Step 1 — XLIFF 打包导出
从 Master Repo 中文版导出待翻译内容：
# 在 Oxygen 中
# 1. 打开中文 Map（如 dita_alpha1pro/alpha1pro_user_guide.ditamap）
# 2. 选择导出目标语言（如 en, ja, fr）
# 3. 导出为 XLIFF 2.0/1.2 格式
输出文件： ubtech_zh_to_en.xliff
Step 2 — 提交翻译平台
将 XLIFF 文件上传至翻译平台（如 AI 创新翻译平台），分配译者并开始翻译。
XLIFF 格式保留了 DITA 的 topic 结构、标签属性和条件标记，翻译平台中不可修改结构标签，仅翻译 <source> 对应的 <target> 内容。
Step 3 — 执行翻译
译者在翻译平台中逐段翻译，平台自动维护以下信息：
- 翻译记忆库（TM）：相同/相似句段自动匹配，提高一致性
- 术语库：自动提示标准术语译法（如"伺服"译为"servo"）
- 质量检查（QA）：数字、标签、术语一致性自动校验
Step 4 — XLIFF 回写
翻译完成后，从平台导出已翻译的 XLIFF 文件，回写到项目中：
# 回写后自动生成目标语言 DITA 文件
# 如 en/ 目录下自动生成对应英文 Topic
目录结构：
├── dita_alpha1pro/
│ ├── topics/ # 中文版源文件
│ └── l10n/
│ └── en/ # XLIFF 回写生成的英文版
│ ├── topics/concepts/
│ └── topics/tasks/
Step 5 — 提交目标语言 Repo
git checkout -b release/ubtech-en-v1.0
git add l10n/en/
git commit -m "[l10n/en] XLIFF回写完成，v1.0英文版初始化"
git push origin release/ubtech-en-v1.0
5.2 路径二：Oxygen AI 翻译流程
Step 1 — 拉取多语言 Repo
翻译团队从 GitLab 拉取本地化翻译仓库：
git clonehttp://139.198.31.90:8888/Jeffrey/bistuedul10n.git
cd bistu-edu-l10n
git checkout -b feature/ubtech-en-translation
Step 2 — AI 辅助翻译（逐一 Topic）
在 Oxygen 中打开中文 Topic，使用 AI 插件组合完成翻译：
| 操作 | AI 插件 | 说明 |
|---|---|---|
| 初译 | 反思翻译 | AI 自动将中文内容翻译为英文，保留 DITA 标签结构 |
| 术语检查 | 术语管理 | 自动匹配术语库，确保"伺服=servo""控制器=controller"等译法统一 |
| 质量审校 | ASD-STE | 检查英文是否符合 Simplified Technical English 规范 |
| 内容优化 | 内容推荐 | 根据上下文推荐更自然的表达方式 |
Step 3 — 人工审校与提交
AI 翻译后，译者进行人工审校，确认：
- 技术术语译法准确（参考 UBTECH 官方英文版对照）
- DITA 标签结构未被破坏（<note>、<step> 等嵌套正确）
- 条件属性（audience、platform）保留完整
- 版本元数据已更新（<vrm version>、<revised> 等）
# 审校通过后提交
git add dita_alpha1pro/
git commit -m "[AI-translate] 安全说明+故障排除，Oxygen AI翻译完成审校"
git push origin feature/ubtech-en-translation
5.3 两种路径对比
| 维度 | XLIFF 打包翻译 | Oxygen AI 翻译 |
|---|---|---|
| 适用规模 | 大批量（100+ topic） | 中小批量（<50 topic） |
| 译者人数 | 多译者并行协作 | 单译者或少量译者 |
| 术语一致性 | 强（术语库统一管理） | 中等（AI+术语插件辅助） |
| 翻译速度 | 较慢（流程环节多） | 快（编辑器内一站式完成） |
| 质量保障 | 强（专业 QA 流程） | 依赖译者审校能力 |
| 推荐场景 | 正式发布版本、多语言同步 | 快速原型、教学练习、AI 辅助 |
🤖 第六章
06UBTECH DITA 实操示例
本章以 UBTECH Alpha 1 Pro 和 Jimu 两个产品的 DITA 手册为实际案例，演示从 Map 规划到最终发布的完整操作过程。
6.1 产品手册结构
| 产品 | DITA Map | Topic 数量 | 说明 |
|---|---|---|---|
| Alpha 1 Pro | dita_alpha1pro/alpha1pro_user_guide.ditamap |
18 个 Topic | 人形机器人用户指南，涵盖安全、操作、故障排除 |
| Jimu 积木机器人 | dita_jimu/jimu_user_manual.ditamap |
37 个 Topic | 可编程积木机器人说明书，涵盖组装、APP、动作编程 |
6.2 Alpha 1 Pro Map 结构解析
<map xml:lang="en">
<title>Alpha 1 Pro User Guide</title>
<!-- Front Matter -->
<topicref href="topics/concepts/c_overview.dita" type="concept"/>
<!-- 法规合规 -->
<topicref href="topics/reference/r_regulatory_compliance.dita">
<topicref href="topics/reference/r_fcc_statement.dita"/>
</topicref>
<!-- 安全信息 -->
<topicref href="topics/concepts/c_safety_intro.dita">
<topicref href="topics/reference/r_safety_instructions.dita"/>
<topicref href="topics/reference/r_safety_warnings.dita"/>
</topicref>
<!-- 开始使用 -->
<topicref href="topics/concepts/c_getting_started.dita">
<topicref href="topics/reference/r_package_contents.dita"/>
<topicref href="topics/concepts/c_parts_components.dita"/>
<topicref href="topics/concepts/c_servo_distribution.dita"/>
<topicref href="topics/concepts/c_controller.dita"/>
<topicref href="topics/concepts/c_battery_charging.dita"/>
</topicref>
<!-- 操作指南 -->
<topicref href="topics/tasks/t_operating_alpha.dita">
<topicref href="topics/tasks/t_power_on_off.dita"/>
<topicref href="topics/tasks/t_reset_position.dita"/>
<topicref href="topics/tasks/t_action_programming.dita"/>
<topicref href="topics/tasks/t_action_program_run.dita"/>
</topicref>
<!-- 故障排除 + 参数 + 支持 -->
<topicref href="topics/reference/r_troubleshooting.dita"/>
<topicref href="topics/reference/r_product_parameters.dita"/>
<topicref href="topics/reference/r_customer_support.dita"/>
</map>
6.3 实操任务：中文版安全说明 Topic
任务目标
将英文版 c_safety_intro.dita 翻译为中文版，并通过 Oxygen AI 插件辅助完成，最后提交到 GitLab。
Step 1 — 创建翻译分支
git checkout main
git pull origin main
git checkout -b feature/ubtech-safety-zh-v1.0
Step 2 — 复制并修改 Topic
将 c_safety_intro.dita 复制为 c_safety_intro_zh.dita，修改以下内容：
xml:lang="en"→xml:lang="zh-CN"- 翻译 <title>、<shortdesc>、<conbody> 内所有文本
- 保留所有 DITA 标签结构不变
Step 3 — 使用 Oxygen AI 辅助翻译
在 Oxygen Author 模式下选中英文段落，依次使用 AI 插件：
| 操作 | 快捷键/菜单位置 | 输出 |
|---|---|---|
| AI 初译 | AI > 反思翻译 > 翻译选中内容 |
中文翻译文本 |
| 术语检查 | AI > 术语 > 检查术语一致性 |
术语匹配报告 |
| 反思审校 | AI > 反思翻译 > 审校模式 |
改进建议列表 |
Step 4 — 校验与本地预览
Ctrl+Shift+V校验单个文件 DITA 合规性- 右键 ditamap → Configure Transformation Scenario → HTML5 预览
- 确认中文渲染正常、标签嵌套正确
Step 5 — 提交并发布
# 提交到 GitLab
git add topics/concepts/c_safety_intro_zh.dita
git commit -m "[c_safety_intro_zh] Alpha 1 Pro安全说明中文版，AI辅助翻译完成"
git push origin feature/ubtech-safety-zh-v1.0
# 在写管用条件发布系统中
# 1. 选择 Repo: bistu-edu
# 2. 选择 Branch: feature/ubtech-safety-zh-v1.0
# 3. 选择 Map: dita_alpha1pro/alpha1pro_user_guide.ditamap
# 4. 构建条件: lang=zh, format=html5
# 5. 点击发布
6.4 复用手册新建产品线（举一反三）
假设要为 UBTECH 新产品"Beta2"创建手册（与 Alpha 1 Pro 结构相似，约 60% 内容可复用）：
| 类别 | 处理方式 | 示例 |
|---|---|---|
| 直接复用 | 用 conref/key 引用，不复制文件 | r_fcc_statement.dita、r_regulatory_compliance.dita |
| 复用改写 | 复制文件到新目录，改前缀，逐段修改 | c_overview.dita、t_power_on_off.dita |
| 全新内容 | 新建 topic | Beta2 特有传感器模块、专属 App 联动 |
结构化复用优先于复制粘贴复用
凡是逐字一致的法规/安全免责声明类内容，务必用 conref 指向公共源，而不是复制文本——这样以后法规更新只改一处。
凡是逐字一致的法规/安全免责声明类内容，务必用 conref 指向公共源，而不是复制文本——这样以后法规更新只改一处。
📚 附录
07附录与资源汇总
A. 账号与访问信息速查
| 系统 | 地址 | 账号/凭据 |
|---|---|---|
| GitLab | 139.198.6.122:8888 | Jeffrey / vGk7sXj6LNQxWG7 |
| GitLab PAT | glpat-i8TJemxAD1PokXoIheEJ6G86MQp1OjcH.01.0w1f6xhdb |
|
| 核心 Master Repo | ray/bistu-edu | UBTECH 机器人 + 飞行器 |
| 本地化翻译 Repo | jeffrey/bistu-edu-l10n | 大模型翻译流程 |
| 条件发布系统 | 58.87.102.99:8080 | 同 GitLab 账号 |
| 操作手册 | 写管用条件发布系统操作手册（金山文档） | |
B. 交付物清单
| 交付物 | 下载/说明 |
|---|---|
| Oxygen XML Author | 官方下载页（Windows） |
| Oxygen AI 插件 | 随 Oxygen 安装包分发，或单独获取安装 |
| 编辑器授权 | 查阅《编辑器授权》文本文件 |
C. DITA 命名规范速查
| 元素 | 命名前缀 | 示例 |
|---|---|---|
| Concept（概念） | c_ |
c_safety_intro.dita |
| Task（任务） | t_ |
t_power_on_off.dita |
| Reference（参考） | r_ |
c_troubleshooting.dita |
| DITA Map | 产品名 + _user_guide.ditamap |
alpha1pro_user_guide.ditamap |
| 分支名 | release/<产品>-<语言>-v<版本> |
release/ubtech-zh-v1.1 |
| Tag 名 | <产品>-<语言>-v<版本> |
ubtech-zh-v1.1 |
D. 初学者 Checklist
首次上手检查清单
☐ 确认 GitLab 账号可正常登录
☐ 使用 PAT 完成至少一次 Clone 操作
☐ 在 Oxygen 中打开 UBTECH Map 并能浏览所有 Topic
☐ 成功修改一个 Topic 并 Push 到 GitLab
☐ 在条件发布系统中成功发布一次 HTML5
☐ 完成至少一个 Topic 的中英翻译练习
☐ 熟悉 Oxygen AI 四个插件的基本操作
☐ 确认 GitLab 账号可正常登录
☐ 使用 PAT 完成至少一次 Clone 操作
☐ 在 Oxygen 中打开 UBTECH Map 并能浏览所有 Topic
☐ 成功修改一个 Topic 并 Push 到 GitLab
☐ 在条件发布系统中成功发布一次 HTML5
☐ 完成至少一个 Topic 的中英翻译练习
☐ 熟悉 Oxygen AI 四个插件的基本操作
E. 常见问题速查
| 问题 | 解决方案 |
|---|---|
| SSH Clone 失败 | 改用 HTTPS + PAT 认证 |
| Push 时冲突 | 先 Pull 再 Push，养成开工前 Pull 的习惯 |
| DITA 校验报错 | 检查标签闭合、note 位置（必须在 section 前）、元素顺序 |
| 发布系统找不到 Map | 确认分支已 Push 到远程，且 ditamap 在仓库根目录或一级子目录 |
| AI 翻译破坏标签 | 使用 Author 模式而非 Text 模式调用 AI，避免修改 XML 标签 |
| 中英文版本号混淆 | 中英文版本号独立管理，在 metadata 中注明对应源语言版本号 |