第八章：术语表、自定义提示词与 JSON 翻译

本章讲三项能显著提升翻译质量与适用范围的高级能力：

术语表（Glossary）：保证专有名词全篇译法一致。
自定义提示词（custom_prompt）：控制翻译风格、领域、特殊要求。
JSON 翻译：只翻译结构化数据中指定的字段。

这三项在 Web 界面、Client SDK、Workflow API 中都可用，本章以 SDK 参数为主线讲解。

8.1 术语表：为什么需要

大模型逐块翻译长文档时，同一个专有名词（人名、地名、技术术语、产品名）可能在不同块被译成不同词。例如小说里的 Jobs 一会儿译「乔布斯」一会儿译「工作」，论文里的 transformer 一会儿「变压器」一会儿「Transformer 模型」。术语表就是用来强制统一这些译法的。

DocuTranslate 提供两种术语表方式：

自动生成术语表：让模型先通读全文，抽取出高频 / 重要术语并给出统一译法，再据此翻译。
手动术语表：你直接提供「原词 → 译词」的字典。

两者可以配合使用。

8.2 自动生成术语表

开启 glossary_generate_enable=True：

from docutranslate.sdk import Client

client = Client(
    api_key="YOUR_API_KEY",
    base_url="https://api.deepseek.com/v1",
    model_id="deepseek-chat",
    to_lang="中文",
    glossary_generate_enable=True,   # 启用自动术语表生成
)
result = client.translate("paper.pdf", convert_engine="mineru", mineru_token="...")
result.save(fmt="html")

启用后，翻译流程会多一个「术语抽取」阶段：模型先扫描文档、生成术语表，再在正式翻译时参考这份术语表，从而实现全篇术语对齐。代价是会多消耗一些 token 和时间，但对术语密集的论文、技术文档、系列小说非常值得。

你还可以通过 glossary_agent_config 对术语抽取所用的模型 / 参数做单独配置（例如用更强的模型抽术语、用便宜的模型做翻译）。

8.3 手动术语表

如果你已经有一份权威译名对照，用 glossary_dict 直接传入：

client = Client(
    api_key="YOUR_API_KEY",
    base_url="https://api.deepseek.com/v1",
    model_id="deepseek-chat",
    to_lang="中文",
    glossary_dict={
        "Jobs": "乔布斯",
        "Apple": "苹果公司",
        "transformer": "Transformer",   # 保留英文不译
    },
)
result = client.translate("article.txt")

手动术语表优先级最高，适合：

有官方 / 团队统一译名规范时；
需要「某些词保持原文不译」时（把译词设成原词即可）；
自动术语表偶有偏差、需要人工兜底时。

在 Web 界面 / MCP 中，也可以上传 JSON 或 CSV 格式的术语表文件（MCP 有 load_glossary_file 工具，见第十章）。

8.4 自定义提示词

custom_prompt 允许你在默认翻译提示词的基础上追加自己的要求，从而控制翻译的风格、语气、领域和特殊规则。示例：

client = Client(
    api_key="YOUR_API_KEY",
    base_url="https://api.deepseek.com/v1",
    model_id="deepseek-chat",
    to_lang="中文",
    custom_prompt=(
        "这是一部科幻小说。请保持文学性和画面感，"
        "人物对话使用口语化中文；专有设定名词首次出现时保留英文并加中文注释；"
        "不要添加任何译者注。"
    ),
)
result = client.translate("novel.epub")

常见用途：

指定领域：如「这是医学论文，请使用规范医学术语」。
控制风格：正式 / 口语 / 文学 / 简洁。
保留格式约定：如「保留所有 Markdown 代码块中的代码不译」。
控制输出：如「不要输出解释，只输出译文」。

自定义提示词与术语表可以叠加使用，共同约束模型行为。

8.5 思考模式与其他质量相关参数

除了术语表和提示词，以下参数也影响翻译质量与成本：

thinking（思考模式）：auto / none / block。文档翻译一般用 none（关闭思考）即可，省 token、更快；对需要复杂理解的内容可尝试开启。环境变量层面取值为 default / enable / disable。
temperature（温度）：默认 0.3，翻译类任务建议保持较低值以求稳定；调高会更「发挥」但可能偏离原意。
chunk_size（分块大小）：默认 3000。太小会增加请求数与拼接损耗，太大可能超模型上下文或降低质量，一般用默认或按模型上下文微调。
force_json：强制模型以 JSON 格式输出，某些工作流用于稳定解析。

8.6 JSON 翻译与 JSONPath

DocuTranslate 支持只翻译 JSON 中指定字段的值，这对翻译 i18n 语言包、配置文件、数据集非常有用。核心是 json_paths，使用 jsonpath-ng 语法。

示例 JSON（lang.json）：

{
  "app": {
    "title": "Welcome",
    "desc": "Please sign in",
    "version": "1.0.0"
  },
  "buttons": ["Save", "Cancel"]
}

只翻译 app.title、app.desc 和所有按钮，保留 version 不动：

client = Client(
    api_key="YOUR_API_KEY",
    base_url="https://api.deepseek.com/v1",
    model_id="deepseek-chat",
    to_lang="中文",
)
result = client.translate(
    "lang.json",
    json_paths=["$.app.title", "$.app.desc", "$.buttons[*]"],
)
result.save(fmt="json")

要点：

json_paths 是一个 JSONPath 表达式列表，只有被匹配到的值才会被翻译。
未匹配的字段（如 version）保持原样，避免误翻版本号、ID、URL 等不该翻译的内容。
常用表达式：$.*（顶层所有值）、$.data.*、$.items[*].name、$..text（递归匹配所有 text）。

用 Workflow API 时，则在 JsonWorkflowConfig 中设置 json_paths（见第七章）。

8.7 组合使用：一个高质量翻译配置

把本章能力组合起来，一个「术语对齐 + 风格可控 + 稳定」的论文翻译配置可能是这样：

client = Client(
    api_key="YOUR_API_KEY",
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    model_id="doubao-seed-1-6-flash",
    to_lang="中文",
    concurrent=16,
    temperature=0.3,
    thinking="none",
    glossary_generate_enable=True,          # 自动术语表
    glossary_dict={"LLM": "大语言模型"},     # 手动兜底关键术语
    custom_prompt="这是计算机领域学术论文，请使用规范中文术语，保留公式与代码不译。",
)
result = client.translate(
    "paper.pdf",
    convert_engine="mineru",
    mineru_token="YOUR_MINERU_TOKEN",
    formula_ocr=True,
    code_ocr=True,
)
result.save(fmt="html")

8.8 小结

术语表解决全篇译名一致：glossary_generate_enable（自动）+ glossary_dict（手动兜底）。
自定义提示词（custom_prompt）控制风格、领域与特殊规则，可与术语表叠加。
JSON 翻译用 json_paths（JSONPath）精确指定要翻译的字段，避免误翻 ID / 版本号等。
配合 thinking、temperature、chunk_size 等参数可在质量与成本间取得平衡。
下一章讲如何把 DocuTranslate 作为 REST API 服务对外提供。