在使用DeepL API翻译JSON文件时，最关键的约束是1MB的固定上传大小限制，这一限制对所有API计划统一适用且无法通过升级套餐来提升。当JSON文件超出该限制时，官方提供了两种解决方案：按顶级键或逻辑章节拆分为多个子文件分别翻译后合并，或提取所有字符串值通过文本翻译API逐条处理后重新插入原始结构。两种方式的适用场景不同，拆分方式适合结构完整且需要整体翻译的JSON，文本API方式适合实际翻译内容少但文件结构复杂的JSON。翻译过程中DeepL仅处理字符串值，键名、数字和布尔值保持原样不变，确保了翻译后JSON文件的技术兼容性。提交前务必确保JSON格式严格有效，不支持JSONC风格的注释或末尾逗号，否则会触发翻译错误。文档翻译API对JSON文件同样适用50,000字符的最低计费规则，在翻译内容较少时评估文本翻译API的替代方案有助于优化成本。
JSON文件在文档翻译API中的上传大小限制
所有API计划统一适用1MB上限
DeepL文档翻译API对JSON格式的文件设置了明确的上传大小限制，无论用户使用的是DeepL API Free还是API Pro计划，单份JSON文件的最大上传容量均为1MB。与其他文档格式不同，JSON格式没有针对不同API计划设置差异化的大小限制，所有用户统一适用这一标准。这一限制适用于通过文档翻译端点提交JSON文件的所有使用场景，超过1MB的JSON文件会被API直接拒绝翻译请求，不会进入后续的处理流程。
1MB限制的含义与适用范围
1MB的上传限制指的是JSON文件的原始文件大小，而非文件中的字符数量。DeepL官方帮助中心明确指出，当前JSON文件的上传限制为1MB，这一限制适用于所有用户，不论其订阅的是哪种API计划。当用户通过网页版翻译器、桌面应用程序或API的document请求提交JSON文件进行翻译时，均需遵守这一大小限制。对于包含大量元数据的JSON文件（如DataCite、Zenodo或Backstage catalog导出数据），文件大小容易超过1MB限制，需要采取额外的处理措施。
JSON格式在文档翻译中的特殊地位
JSON文件在DeepL文档翻译API中属于受支持的文件格式，但其上传限制与其他格式存在显著不同。例如，API Free和API Pro对JSON格式的文件大小限制完全一致均为1MB，不因计划升级而提升。DeepL帮助中心也明确说明，JSON文件的上传限制为1MB，如果文件超出此限制，建议将其拆分为多个较小的JSON文档分别翻译。这种处理方式有别于DOCX等格式通过客户端库压缩媒体内容的优化路径，JSON文件的拆分需要用户自行完成。
不同API计划下JSON文件大小限制的一致性
与DOCX等格式的差异化设计
DeepL的文档翻译API在文件大小限制的设计上，对不同格式采取了差异化的策略。对于DOCX和PPTX等格式，DeepL API提供了minify功能：.NET、PHP和NodeJS客户端库可以通过临时提取大型媒体格式来压缩文件，然后再发送给DeepL API，翻译完成后重新插入媒体内容。这使得部分超出大小限制的文档仍可通过API处理。而JSON格式没有类似的压缩或预处理机制，1MB的限制是硬性约束，无法通过客户端库的功能绕过，任何超过此大小的JSON文件都会被API直接拒绝。
与图片格式等其他格式的计费差异
JSON格式在DeepL文档翻译API中的定位与图片格式（PNG、JPG）等Beta测试功能有所不同。图片格式的文件上传大小统一为3MB，且其翻译不计入计费范围。JSON格式在计费上适用于文档翻译的规则，包括最低计费门槛和字符配额消耗，但其1MB的上传限制比图片格式更为严格。用户在使用API翻译JSON文件时，需要同时关注文件大小限制和最低计费规则两个维度，确保文件大小不超过1MB且了解最低计费的影响。
区分文件大小与字符数限制
需要注意的是，JSON文件的1MB限制与字符数限制是两个独立的约束。即使JSON文件中的实际文本字符数很少，只要文件总大小超过1MB，仍然会被API拒绝。这种情况在处理包含大量嵌套结构或长键名的JSON文件时尤为常见，因为键名和结构标识符虽然不会被翻译，但仍然占用文件大小空间。如果文件大小接近1MB上限但实际需要翻译的字符串值较少，用户可以考虑提取字符串值通过文本翻译API处理，这是一种更有效的规避方式。
超过1MB上传限制的拆分处理方案
按顶级键拆分的操作方法
当JSON文件超过1MB的上传限制时，DeepL官方建议的第一个处理方案是将文件拆分为多个较小的JSON文档，拆分方式可以为每个顶级键对应一个文档。例如，如果一个JSON文件包含多个顶级键如”products”、”categories”和”settings”，用户可以将这三个顶级键分别提取出来，保存为三个独立的JSON文件。每个拆分后的子文件分别提交翻译，DeepL会独立处理每个文件中的字符串值。翻译完成后，用户将各部分的译文重新合并回原始的JSON结构中，确保整体结构的完整性。
按逻辑章节拆分的替代策略
除了按顶级键拆分之外，DeepL还建议用户按照逻辑章节对大型JSON文件进行切割。这种拆分方式适合JSON文件的结构按功能或内容区域组织，但顶级键较少的场景。用户可以根据文件内容的逻辑分组确定拆分边界，将相关联的内容保留在同一文件中，便于翻译后的拼装管理。拆分时建议记录每个子文件在原始结构中的位置路径，在合并译文时能够准确还原。无论是按顶级键还是按逻辑章节拆分，最终都需要在翻译完成后进行合并操作，确保译文重新组装回完整的JSON格式。
拆分处理后的合并要点
拆分JSON文件翻译后，合并译文时需要注意保持原始JSON结构的完整性。DeepL在翻译JSON文件时只翻译字符串值，键名、数字和布尔值保持不变。这一特性简化了合并过程，因为所有键名和结构标识符在翻译前后保持一致，用户只需将每个拆分文件的译文按原始路径重新组装即可。合并过程中应确保所有字符串值的顺序和位置与源文件完全对应，避免因错位导致的引用错误。对于翻译后格式验证，建议使用JSON校验工具检查合并文件的语法正确性。
提取字符串值后通过文本API翻译的替代方式
字符串值提取与翻译的工作流
DeepL官方提供的另一个解决方案是提取JSON文件中的所有字符串值，分别翻译后再重新插入到原始JSON结构中。具体操作上，用户先遍历整个JSON文件，将所有字符串值提取到一个单独的可翻译内容列表中，通过DeepL的文本翻译API（/v2/translate端点）处理这些字符串，然后将翻译后的结果按原始路径逐一插回JSON文件中。这种方式不需要处理JSON文件中的键名和结构标记，只翻译实际需要转换的文字内容。对于字符串数量不多但文件整体结构复杂的大型JSON文件，这种方法比拆分更高效，且避免了每份子文件单独消耗文档翻译配额。
文本翻译API的优势与适用条件
提取字符串值后使用文本翻译API处理的替代方式，最大的优势在于文本翻译API没有1MB的文件上传大小限制。每个文本字符串元素不应超过30KB，但可以一次性提交多个独立的文本元素进行翻译。这种方式适合从JSON中提取的字符串总量较大但单个字符串较短的情况，用户可以通过批量提交处理大量短字符串。文本翻译API也不受文档翻译API的50,000字符最低计费规则的限制，按实际字符数精确计费，对于字符串数量较少但JSON文件结构复杂的场景更具成本优势。
两种处理方式的场景对比
用户应根据具体的JSON文件特征选择合适的处理方式。如果JSON文件大小超过1MB的主要原因是结构复杂、嵌套层次多或键名冗长，但实际需要翻译的字符串值数量较少，提取字符串值通过文本API翻译是更高效的选择。这种方式可以避免文档翻译API的最低计费，同时不受1MB文件大小限制的约束。如果JSON文件的结构相对扁平且所有顶级键下的内容都需要完整翻译，将文件按顶级键拆分为多个子文件后分别通过文档API翻译更为便捷，因为可以一次性处理整个文件的所有字符串值而无需手动提取和重新插入。
JSON翻译的字符计费规则与最低门槛
JSON文件翻译的最低计费规则
JSON文件通过DeepL文档翻译API进行处理时，同样适用文档翻译的最低计费规则。与Word、PPT、Excel和PDF格式一致，每次JSON文件翻译至少按50,000字符计费，即使文件实际包含的字符串值字符数不足50,000，也会按此标准收取费用。这一规则适用于所有通过/document端点提交的JSON文件翻译请求。如果JSON文件中实际需要翻译的字符串值较少，文档翻译API的最低计费可能导致单位字符成本显著偏高，用户应评估使用文本翻译API的替代方案是否更具成本效益。
字符计费的对象范围
DeepL在翻译JSON文件时只统计字符串值中的字符数，键名、数值、布尔值和null值不会被计入计费字符。例如，在{"greeting": "Hello, world!"}中，只有”Hello, world!”这13个字符会被计入计费范围，键名”greeting”不计费。这种计费方式对于键名冗长但实际翻译内容较少的JSON文件相对有利，因为计费仅针对实际需要翻译的文字内容。但文档翻译API的最低50,000字符计费规则意味着即使实际翻译字符数远低于此门槛，仍需按此标准支付费用。
与文本翻译API的计费对比
JSON文件通过文档翻译API和通过文本翻译API处理在计费上存在本质差异。文档翻译API适用于完整JSON文件的批量翻译，但受50,000字符最低计费规则约束，适合包含大量字符串值的大型JSON文件。文本翻译API按实际字符数精确计费，没有最低门槛，适合从JSON中提取的少量字符串值的翻译需求。用户在评估翻译JSON文件的成本时，应综合考虑文件大小、字符串值的数量和分布、以及是否需要保留完整的JSON结构来决定使用哪种API方式。
嵌套结构与键名在翻译中的处理规则
字符串值的遍历翻译机制
DeepL在处理JSON文件时，会递归遍历所有层级的对象和数组，提取每一个字符串值进行翻译。嵌套的对象和数组会在所有层级中被遍历处理，所有可翻译的字符串值都会被提取并转换为目标语言。例如，{"user": {"name": "John", "bio": "Developer"}}中的”John”和”Developer”都会被提取翻译，而”user”和”name”等键名保持不变。这种递归处理机制确保了嵌套结构中的所有文字内容都能被正确翻译，用户无需手动提取深层字符串。
键名与数字值的处理规则
JSON键名在DeepL的翻译过程中不会被修改，无论键名包含自然语言词汇还是技术标识符，均保持原样输出。DeepL在处理JSON文件时只翻译字符串值，JSON键、数值、布尔值和嵌套对象不会被翻译。例如，键名”product_name”不会被翻译为”产品名称”，只有其对应的字符串值才会被转换。数字值（如价格、数量）和布尔值（true/false）同样保持不变。这一设计确保了JSON文件的结构完整性和技术兼容性，翻译后的文件可以直接被应用程序解析使用，键名和数据类型不会因翻译发生变化。
排除特定内容翻译的操作方法
如果用户希望将JSON文件中部分自然语言内容排除在翻译范围之外，DeepL提供了编码层面的解决方案。用户可以将这些内容编码为非字符串类型（数字、布尔值或null），或者将它们封装在键值对中，在应用程序端忽略该键值对即可。这种排除机制对于包含代码注释、占位符或不应翻译的标记内容非常实用。提交的JSON文件必须为严格、可解析的标准JSON格式，不支持JSONC风格的注释或末尾逗号。DeepL帮助中心明确提醒，如果JSON文件包含尾随逗号或注释，将导致翻译错误，用户需要将文件转换为有效的JSON格式后再上传。
