在实际使用DeepL API集成术语表功能时,建议开发者按照从查询支持到验证生效的顺序逐步推进。首先通过GET /v3/languages?resource=glossary查询当前API版本中术语表支持的语言对,确认目标语言对在支持范围内。然后调用POST /v3/glossaries创建术语表,提交术语条目时使用TSV或CSV格式,每行一个术语配对,确保没有重复的源语言术语对应不同译文的情况。术语表创建后检查返回的ready字段,如果为false则轮询等待直到确认术语表已就绪。在发起翻译请求时,将glossary_id添加到请求体的/v2/translate或/v2/document调用中,同时确保请求中明确指定了source_lang参数。翻译完成后抽样检查术语表中的术语在译文中的实际表现,如果发现某条术语未被应用,检查翻译请求的源语言和目标语言是否与术语表的语言对精确匹配。对于需要构建全自动翻译流水线的场景,可以将术语表的创建、验证和应用步骤编写为可复用的脚本或函数,在每次处理新的文档类型或新增术语时调用这些脚本完成术语表的自动化初始化和更新。DeepL官方库(PHP、.NET、Python等)提供了封装好的术语表管理方法,开发者使用官方库可以减少直接处理HTTP请求的繁琐工作,更高效地集成术语表功能。

API术语表功能的技术支持范围
术语表在API翻译请求中的完整支持
DeepL API在翻译文本和文档时,通过glossary_id参数完整支持术语表的应用。开发者在调用翻译接口时,只需在请求体中指定已创建的术语表ID,DeepL翻译引擎便会在处理翻译时强制应用术语表中预设的源语言到目标语言的术语映射规则。文本翻译接口/v2/translate和文档翻译接口/v2/document均支持glossary_id参数,这意味着无论是翻译短文本还是上传完整的Word、PPT或PDF文件,术语表都能正常生效。DeepL官方PHP库的示例代码展示了术语表的典型用法——翻译请求中指定glossary选项后,术语表中的规则会被强制执行,例如将“artist”强制译为“Maler”而非DeepL默认的“Künstler”。
API创建术语表的方式与格式要求
DeepL API提供了完整的术语表管理端点,开发者可以通过API创建、编辑、删除和检索术语表。创建术语表时,开发者需要提交术语表的名称、源语言、目标语言以及术语条目列表,条目格式支持TSV(制表符分隔值)或CSV(逗号分隔值)两种格式,每一行包含源语言术语和目标语言译文的配对。DeepL API v3端点还支持多语言术语表的创建,一个术语表可以同时包含多个语言对的映射关系,例如英译德词典和英译法词典可以存储在同一个术语表中,在翻译时根据具体的源语言和目标语言自动选择对应的词典。术语表创建成功后,API返回一个唯一的glossary_id,开发者需要将此ID保存下来用于后续的翻译请求调用。
API术语表与网页版术语表的关系
DeepL API使用的术语表与网页版翻译器和桌面应用中使用的术语表共享同一账户体系,API用户创建的术语表会自动同步到DeepL账户中,在网页版的术语表管理界面中可见且可编辑。反之,用户在网页版手动创建的术语表也可以通过API进行管理和调用,两者之间的术语数据完全互通。DeepL官方帮助中心明确指出,“通过DeepL API创建和管理术语表”是术语表功能的核心能力之一,API用户可以将术语表功能集成到自己的产品中,进一步简化应用中的翻译流程。但API创建的术语表在生成后可能需要短暂的处理时间,开发者应当在翻译请求前检查术语表的ready状态,确认术语表已就绪后再发起翻译请求。
API翻译请求中启用术语表的操作细节
翻译请求中glossary_id参数的传递方式
在DeepL API的翻译请求中启用术语表,需要在请求体中包含glossary_id参数,并将值设置为已创建的术语表ID。文本翻译API的标准调用格式为POST /v2/translate,请求体中的glossary_id参数与text参数平级,用于指定当前翻译请求应用的术语表。文档翻译API同样通过glossary_id参数来应用术语表,开发者在上传文档的请求中包含该参数即可让术语表规则在文档翻译中生效。DeepL官方文档中强调,使用术语表时翻译请求中的source_lang参数是必需的,术语表功能尚不支持与自动源语言检测同时使用,开发者必须明确指定源语言代码以确保术语表的正确匹配。
API术语表应用的前提条件与限制
使用API术语表需要满足几个前提条件,开发者在集成前应当确认这些条件已经达成。翻译请求的源语言和目标语言必须与术语表中定义的语言对完全匹配,一个英译中的术语表无法应用在英译德或法译中的翻译任务中。翻译请求中必须指定source_lang参数,术语表不支持与自动源语言检测功能同时使用,如果请求中未明确指定源语言,DeepL会忽略术语表的使用。术语表适用于所有目标语言变体——一个目标语言为英语(根语言代码en)的术语表,可以应用于翻译到美式英语(en-US)和英式英语(en-GB)的翻译任务中,无需为每个语言变体单独创建术语表。术语表功能仅支持特定的语言对组合,开发者可以通过GET /v3/languages?resource=glossary接口动态查询当前账户支持术语表的语言对。
API术语表与语言变体的兼容规则
DeepL API的术语表在设计上基于语言根代码而非特定语言变体,这一规则让开发者能够用一个术语表覆盖同一语言的所有区域变体。当开发者创建了一个目标语言为英语(根代码en)的术语表,它可以同时用于翻译到美式英语(en-US)和英式英语(en-GB)的翻译请求中,不需要为每种英语变体分别创建术语表。中文同样适用此规则——一个目标语言为中文(根代码zh)的术语表,既适用于简体中文翻译也适用于繁体中文翻译。DeepL官方文档建议开发者在创建术语表时使用根语言代码,确保术语表在不同语言变体场景中的通用性。当翻译请求中使用了区域变体语言代码时,DeepL会自动匹配对应根语言的术语表进行处理。
API术语表与语音翻译术语表的区别
语音翻译中的Spoken Terms功能概述
DeepL Voice API提供了与标准术语表功能不同的“Spoken Terms”(口语术语)功能,两者的定位和使用场景有明确区分。Spoken Terms是单语术语集合,用于确保语音识别阶段特定词汇能够被正确识别和转录,例如公司名称、产品名称、人名和专有名词等。Spoken Terms本身只影响语音如何被识别,不涉及翻译过程——它们确保特定的词在语音转文字时被拼写为用户指定的形式,而不是被语音引擎转录为其他相似的词。Spoken Terms通过/v3/spoken-terms端点管理,每个术语列表只针对单一语言,在创建Voice API语音会话时通过spoken_terms_id参数来应用,仅对语音会话的源语言生效。
Glossaries与Spoken Terms的协同使用
在需要同时控制语音识别准确性和翻译术语一致性的场景中,Glossaries和Spoken Terms可以同时在一个Voice API会话中协同工作。开发者创建语音会话时,可以同时传递spoken_terms_id参数和glossary_id参数——Spoken Terms控制语音到文本的转录准确性,确保品牌名和专有名词以正确的拼写被识别;Glossaries控制文本到译文的一致性,确保品牌名和专有名词以预设的标准译法出现在翻译结果中。DeepL官方文档明确说明:“Spoken Terms控制语音如何被识别,Glossaries控制识别出的文本如何被翻译”,两者在语音翻译流程中分别作用于不同的环节,可以叠加使用实现语音识别和翻译输出的双重控制。
两者在API管理方式上的差异
Glossaries和Spoken Terms在API的管理接口和数据结构上存在显著差异。Glossaries使用/v3/glossaries端点管理,包含源语言到目标语言的术语映射,支持编辑和替换操作,适用于标准文本翻译和文档翻译请求。Spoken Terms使用/v3/spoken-terms端点管理,是单语言的术语列表而非语言对映射,主要服务于DeepL Voice API的语音识别场景,每个术语列表的字符容量有限制(最多300字符),需要将预算集中在最重要的术语上。Spoken Terms目前对DeepL API Pro计划和Voice API用户开放,开发者需要检查自己的计划是否包含该功能。Glossaries则广泛支持于DeepL API Free和Pro计划中,覆盖了文本翻译和文档翻译的主流使用场景。
API术语表的实际应用案例
技术文档翻译中的术语一致性保障
在实际的API集成案例中,术语表功能被证明能够显著提升技术文档翻译的术语一致性,甚至能改善翻译的完整性。一位开发者在使用DeepL API翻译PDF技术规范文档时发现,未使用术语表的翻译结果中出现了术语不一致的现象——例如PDF专有名词“null”(小写关键词)在译文中被不一致地译为“NULL”或“Null”,导致技术内容不精确。通过从规范文档中提取71个定义术语,构建了一个56条术语的英译日术语表并注册到DeepL API后,同一段落的翻译不仅术语表达全部统一为正确的PDF关键词,还意外解决了之前翻译中整句被省略的问题。这个案例展示了API术语表在对术语一致性有严格要求的技术文档翻译场景中的双重价值——不仅保证了术语的精确翻译,还可能通过术语锚定提高了翻译引擎对完整上下文的处理能力。
电商和软件本地化中的短文本翻译优化
对于电商平台产品名称、软件界面按钮文案和用户界面术语等短文本翻译,API术语表在保持术语一致性方面的价值尤为突出。电商平台上同一个产品名称或品类术语可能在数百个产品详情页、购物车页面和订单确认页面中重复出现,没有术语表约束时,即使翻译引擎质量再高,不同批次的翻译也可能产生不一致的译法。通过API将核心产品术语和品类术语预先录入术语表,翻译请求中启用glossary_id参数后,所有页面中同一术语的翻译自动保持统一。DeepL官方功能页面将“电商平台的产品本地化”列为核心应用场景之一,强调术语表能够“确保技术术语、产品名称和企业专属表达在多种语言中始终一致”。API的批量翻译能力与术语表结合,开发者可以构建自动化的多语言发布流水线,每次新增产品时系统自动调用DeepL API翻译并应用术语表。
API与MCP服务器组合的自动化术语提取流程
在技术文档翻译的进阶场景中,开发者将DeepL API的术语表功能与MCP(模型上下文协议)服务器组合,构建了从文档自动提取术语到注册术语表再到批量翻译的完整自动化流程。开发者构建了一个PDF规范文档的MCP服务器,其get_definitions工具能够自动从规范文档中提取所有定义术语。提取出的术语经过人工分类和翻译后,通过脚本调用DeepL API的POST /v2/glossaries端点注册为术语表,随后DeepL MCP服务器的翻译工具在每次翻译请求中携带glossaryId参数强制执行术语规则。这一工作流实现了术语提取、术语表构建和术语强制应用的全链条自动化,将术语管理从人工整理升级为数据驱动的自动化流程,为API术语表的规模化应用提供了可复用的架构模式。
API术语表使用的常见注意事项
术语表创建时的语言对匹配检查
开发者在使用API创建术语表前,应当确认目标语言对是否在DeepL的术语表支持范围内,避免因语言对不支持而创建失败。DeepL API提供了GET /v3/languages?resource=glossary接口,开发者调用该接口可以获取当前API版本支持术语表的所有语言对列表,以此作为创建术语表前的动态检查依据。不同编程语言的DeepL官方库也提供了相应的检查函数,例如PHP库中的getGlossaryLanguages()函数返回所有支持的GlossaryLanguagePair对象数组。术语表目前覆盖了DeepL翻译服务中的主流语言组合,但并非所有语言对都支持,开发者在构建依赖术语表功能的应用时应当包含语言对检查逻辑,在用户选择的语言对不支持时给出清晰的提示和引导。
API术语表创建后的就绪状态验证
术语表通过API创建后并非立即可用,开发者应当在翻译请求前检查术语表的ready状态,确保术语表已准备就绪。DeepL API在创建术语表的响应中会返回一个ready布尔值字段,当该字段为false时,术语表仍在后端处理中,此时无法用于翻译请求。在术语表创建过程中,DeepL需要对用户提交的术语条目进行格式校验和索引构建,尤其是条目较多或格式复杂的术语表,处理时间可能长达数秒。开发者应当在创建术语表后检查ready状态,如果为false则需要等待并轮询检查,直到ready变为true后再发起翻译请求。DeepL官方文档的API参考中明确说明:“如果创建的术语表尚未就绪,您需要等待并检查术语表的就绪状态,然后才能用于翻译请求”。
术语表条目冲突与优先级规则
当同一源语言术语在术语表中被赋予了多个不同的目标语言译文时,DeepL API会如何处理这种冲突是开发者需要提前了解的规则。术语表创建时,DeepL会验证术语条目中是否存在相同的源语言术语对应不同的目标语言译文,如果存在这种冲突,API会返回错误提示并拒绝创建术语表。这一设计确保术语表中不存在二义性,每个源语言术语在同一个术语表中有且仅有一个标准译文。当开发者需要为同一术语在不同上下文中使用不同的译文时,正确的做法是创建多个术语表,在翻译不同类型的内容时选择对应的术语表应用。DeepL术语表功能还支持在拥有多个术语表的情况下设置优先级顺序,实现更精细的控制。
常见问题FAQ
DeepL API Free计划支持术语表功能吗
glossary_id参数应用术语表规则。但API Free计划在术语表的数量和每条术语表的条目容量上可能受到更严格的限制,具体配额可在账户的“计划限制”页面查看。语音翻译专用的Spoken Terms功能则仅对特定计划开放,API Free计划目前不包含该功能。API翻译中使用术语表时必须指定源语言吗
source_lang参数是必需的,术语表功能尚不支持与自动源语言检测同时使用。如果开发者在翻译请求中未明确指定源语言而尝试启用术语表,DeepL会忽略术语表的应用。开发者应当在调用翻译接口时确保在请求体中明确传入source_lang参数,并且该参数必须与术语表中定义的源语言代码一致。通过API创建的术语表能在网页版中编辑吗
术语表和Spoken Terms可以在同一个Voice API会话中同时使用吗
spoken_terms_id参数和glossary_id参数,两者分别作用于语音识别的转录环节和文本翻译环节。Spoken Terms确保品牌名和专有名词在语音转文本时被正确拼写,Glossaries确保转录后的术语在翻译时使用预设的标准译法。

