
XLIFF文件版本兼容性要求
官方支持XLIFF 1.2及以上版本
DeepL API对XLIFF文件的版本支持范围较为广泛,官方文档明确支持XLIFF 1.2、2.0和2.1三个版本。用户在通过API上传XLIFF文件之前,应当确认文件头部声明的版本号是否在DeepL的官方支持列表内,不支持的版本将导致翻译请求被拒绝或处理异常。部分第三方文章声称DeepL仅支持XLIFF 2.1版本,但DeepL官方帮助中心已明确指出支持1.2及以上版本。开发者应当优先参考DeepL官方文档而非第三方资料,以确保版本判断的准确性。
不同版本在翻译处理中的差异
XLIFF 2.0及更早版本在翻译后可能存在部分结构细节的丢失,包括单元之间嵌入的注释、内联元素上的属性顺序以及微小的空白差异。DeepL官方在帮助中心中对此有明确说明,2.1版本在结构保留上优于2.0版本。对于需要完整保留原始XLIFF文件中所有注释和结构细节的翻译项目,建议优先使用XLIFF 2.1格式的文件进行翻译。如果源文件为1.2版本且结构完整性要求较高,开发者在翻译前需要评估2.0版本可能带来的细节丢失风险是否可接受。
版本转换的实践建议
许多课程创作工具(如Articulate Rise 360)导出的XLIFF文件为1.2版本,而DeepL对2.1版本的结构保留效果最佳。如果用户在使用DeepL翻译1.2版本XLIFF时发现结构细节丢失,可以考虑将文件升级至2.1版本后再提交翻译。版本转换可以通过XLIFF编辑器或自定义脚本完成,转换过程需要确保文件中所有核心翻译单元的内容完整迁移。对于不需要完整保留注释和属性顺序的翻译项目,1.2版本文件可以直接在DeepL中处理而无需额外转换。
源语言与目标语言的处理规则
请求级语言参数覆盖文件内声明
XLIFF文件中的每个<file>元素可以声明独立的source-language属性,但DeepL API在翻译时会忽略这些文件内部的源语言声明,统一使用API请求中source_lang参数的值来处理所有分段。这意味着无论XLIFF文件中各文件块声明了什么源语言,实际翻译时都按照请求参数中指定的单一源语言执行。如果XLIFF文件中包含多种源语言的混合内容,DeepL无法自动识别不同分段的不同源语言,所有内容都将按请求中指定的源语言处理。开发者在上传XLIFF文件前应确认文件中所有待翻译文本确实属于请求中指定的源语言,否则翻译结果可能出现语义错误。
trgLang属性与目标语言的冲突
XLIFF文件根元素<xliff>中的trgLang属性如果与DeepL API请求中指定的target_lang参数不一致,DeepL会直接拒绝请求并返回”Invalid target language”错误。即使API请求中的目标语言代码本身是有效的,文件内部的trgLang属性值仍会被优先检查,不匹配时请求被拒。开发者在提交XLIFF翻译请求前,应确保文件根元素的trgLang属性与API请求中的target_lang完全一致,或在预处理步骤中移除或修正该属性。翻译完成后,DeepL会更新输出文件中的trgLang属性为请求中指定的目标语言值,开发者无需手动修改。
源语言与目标语言相同的处理规则
DeepL API的通用规则要求源语言与目标语言不同,否则请求将被拒绝并返回HTTP 400错误。此规则同样适用于XLIFF文件翻译,提交源语言与目标语言相同的XLIFF文件将被DeepL拒绝处理。开发者应在调用API之前检查请求参数中的source_lang和target_lang是否相同,避免因无效请求消耗API调用配额。对于需要生成同一语言不同地区变体的场景(如英式到美式英语),应使用Write API而非翻译API处理XLIFF内容。
XLIFF翻译单元的处理规则
source元素的翻译判断标准
DeepL在处理XLIFF文件时,会将<source>元素中的文本内容作为待翻译的源文本提取并处理。每个<source>元素独立作为翻译分段,意味着XLIFF文件中包含的不同源语言文本被分段独立处理。并非所有<source>元素都会被翻译,DeepL会检查state属性:当state属性值为initial、缺失或不为translated时,元素内容才会被纳入翻译范围。如果<source>元素的state属性已经是translated或final,DeepL默认不会重新翻译该分段,这有助于保护已经人工审核的译文不被覆盖。
target元素的生成与位置
翻译完成后,DeepL会将生成的译文放置在对应<source>元素的同级<target>元素中,两者共同归属于同一父元素<segment>。输出文件同时保留原始源文本和新生成的译文,方便用户对比确认翻译质量。如果原始XLIFF文件中已存在<target>元素且<source>的state属性为translated,DeepL默认不会覆盖现有译文。如果需要强制重新翻译所有内容,开发者应预先将<source>的state属性统一修改为initial后再提交请求。
translate属性的排除作用
XLIFF元素上的translate="no"属性标记的内容会被DeepL排除在翻译范围之外,系统不会提取这些元素中的文本内容。这一属性常用于标记品牌名称、代码片段或不需要翻译的专有名词,开发者在准备XLIFF文件时应当合理使用translate="no"属性减少无效翻译。DeepL在处理XLIFF时会完整保留标记为translate="no"的元素及其内容,确保非翻译内容在输出文件中与原位置一致。
文件大小与字符计费规则
单文件大小上限
DeepL API对XLIFF文件的上传大小设定为10MB,超出此限制的文件将无法通过API提交翻译请求。10MB的XLIFF文件通常包含数万到数十万个翻译单元,足以覆盖绝大多数企业级翻译项目需求。对于包含大量内联标签和属性的复杂XLIFF文件,文件体积可能在不包含大量文字时已达到上限,开发者应在文件准备阶段检查文件大小是否在允许范围内。如果XLIFF文件超过10MB,可以将其拆分为多个较小的XLIFF文件分别提交翻译,但需注意拆分可能影响跨分段的术语一致性。
XLIFF不计入最低字符门槛
DeepL API对XLIFF格式的文档翻译采用精确字符计费,不适用每份文档最低50,000字符的计费规则。这一规则意味着小型XLIFF文件(如仅包含数百字符的界面翻译文件)仅按实际字符数计费,不会因最低消费门槛而产生额外费用。精确计费规则使XLIFF成为处理小型翻译项目的经济选择,相比Word或PDF格式每个文件最低计费50,000字符的规则,XLIFF在小文件翻译上的成本优势明显。开发者可以放心地通过API频繁提交小型XLIFF文件,无需因最低字符门槛而合并多个文件为一个请求来降低成本。
字符计费的精确统计方式
DeepL API对XLIFF文件的字符统计基于源文本中所有<source>元素内容的Unicode字符总数,不包括XML标签、属性和注释字符。统计范围仅限于实际需要翻译的文字内容而非整个文件中的XML结构,这意味着开发者可以通过合理使用translate="no"属性减少待翻译内容来有效降低计费字符数。XLIFF格式的精确计费特性使其成为频繁增量翻译的优选格式,文件体积的微小变化会直接反映在计费金额上,不存在最低消费的隐藏成本。
支持XLIFF翻译的API计划
可用计划的完整列表
DeepL API翻译XLIFF文件的功能适用于多个API计划,包括API Free、API Pro、API Developer和API Growth。DeepL Pro的网页翻译器和桌面应用也支持XLIFF文件翻译,功能覆盖范围从免费到企业级方案均包含此格式。用户在订阅任一API计划后均可通过文档翻译端点上传并处理XLIFF文件,无需额外激活该格式的特殊权限。不同计划在XLIFF翻译上的主要差异在于字符配额和文件数量限制,而非对XLIFF格式本身的支持程度。
各计划的字符配额差异
DeepL API Free计划每月提供500,000字符的免费翻译额度,适用于XLIFF文件翻译的测试和小规模项目。API Developer计划提供1,000,000字符的一次性总额度,适合开发阶段的集成测试和有限规模的生产使用。API Growth计划按月或按年计费,月度方案包含1,000,000字符,年度方案包含12,000,000字符,超出部分按量计费。API Pro计划不设字符上限,根据成功请求中的字符数精确计费,适合翻译量不可预测或持续增长的企业级项目。
预付费与按量付费的选择建议
翻译量稳定且可预测的企业项目适合选择API Growth的年付方案,预先购买12,000,000字符获得更低的单位字符成本。翻译量波动较大或处于项目初期的开发者可以选择按量付费的API Pro计划,避免因预估不准确导致的配额浪费或超额费用。API Free计划的500,000字符月额度对测试和小型翻译项目足够使用,但接近额度上限时需提前规划升级方案以避免服务中断。开发者在选择计划时应结合预计处理的XLIFF文件数量和平均文件大小进行成本估算,确保所选计划在性价比和配额充足度上均满足需求。
特殊场景下的处理注意事项
不同源语言混合的XLIFF文件处理
DeepL API的XLIFF翻译处理方式是将<source>元素作为独立分段处理,这一机制理论上允许单个XLIFF文件中包含不同源语言的分段。但在实际使用中,DeepL不保证对未选择源语言的翻译准确性,因此包含混合源语言的XLIFF文件可能产生不可预测的结果。最安全的做法是为每种源语言准备独立的XLIFF文件,并分别使用对应的source_lang参数提交翻译请求。如果必须在一个XLIFF文件中处理混合源语言,开发者应确保每个<source>元素的state属性正确标记已翻译状态,并为每个分段单独维护术语一致性。
XLIFF 2.0版本的结构细节限制
DeepL官方在帮助中心中明确指出,对于XLIFF 2.0版本的翻译,注释和次要结构细节可能无法完整保留。这些可能丢失的细节包括单元之间嵌入的注释、内联元素上的属性顺序以及微小的空白差异。需要完整保留原始文件中所有注释和结构细节的翻译项目应当优先使用XLIFF 2.1版本的文件,以获得最完整的结构保留效果。如果必须使用2.0版本,开发者应确认结构细节丢失对下游处理的影响程度,必要时在翻译完成后通过人工方式恢复关键的注释和属性排序。
trgLang属性错误的快速排查
当DeepL API返回”Invalid target language”错误而用户确认API请求中的target_lang参数完全正确时,问题通常出在XLIFF文件根元素的trgLang属性上。开发者应检查XLIFF文件中<xliff>根元素是否存在trgLang属性,其值是否与API请求中的目标语言代码完全一致。最彻底的解决方式是直接移除XLIFF文件中的trgLang属性,DeepL会在翻译完成后自动在输出文件中设置正确的目标语言值。如果移除属性后仍出现错误,应检查文件是否包含其他与目标语言相关的自定义属性,这些属性可能在XML命名空间中声明,需要逐一排查。
常见问题FAQ
DeepL API支持哪些版本的XLIFF文件?
XLIFF文件中的源语言如何确定?
元素声明的source-language属性,统一使用API请求中source_lang参数的值处理所有分段。上传前应确认文件中所有内容确实属于请求指定的源语言。

