简介OpenRTB 2.5中文翻译文档是一份面向国内程序化广告开发者、算法工程师与计算广告从业者的协议解读资料旨在消除英文原版文档的语言障碍帮助读者快速理解实时竞价通信流程与核心数据结构。资源共1个PDF文件整体大小约1.36MB已有707人学习下载适合在研究、联调和接入OpenRTB时随时对照查阅。文档按OpenRTB 2.5规范展开系统说明Bid Request与Bid Response的请求/响应链路逐一解释Impression、User、Device、Site、App、Bidder Seat、Price Floors、Ad Slot等对象并包含Ext扩展字段的用途。对广告位ID、用户画像、上下文信息、时间戳、拍卖规则、出价金额、创意广告信息、操作系统/浏览器/设备型号等细节均有对应描述还介绍了JSON格式传输以及GDPR隐私处理、视频/音频/富媒体广告支持。这份中文翻译可降低协议落地门槛尤其适合正在搭建ADX/SSP/DSP或从事程序化交易系统研发的初中级工程师作为案头参考提升竞价联调与定向策略实施效率。1. OpenRTB 2.5 的中文翻译文档为什么值得投入一版时间OpenRTB 2.5 是广告程序化交易里绕不开的接口协议IAB 在 2016 年发布的这版规范定义了 BidRequest、BidResponse、SeatBid 这些对象直到今天 DSP、SSP、AdExchange 之间的竞价报文仍大量沿用这套结构。很多团队的做法是直接把英文规范丢给后端遇到字段含义含糊的地方再群里互相问问完答案还不一定对。我做过两轮 OpenRTB 2.5 的中文翻译文档第一版就是纯翻译第二版才把它做成团队真正在用的排错手册。最反直觉的经验是翻译文档的价值不在“中文”而在翻译过程中必须把字段边界、计量单位、必填条件全部钉死否则联调时一个 price 单位就能让你排查两天。这个方向适合 DSP/SSP 的接入研发、广告算法工程师以及刚接手 RTB 项目、需要快速建立名词体系的新人。2. 把 OpenRTB 2.5 模型拆开再合上请求与响应里的关键对象翻译的第一步不是动笔而是先确认你到底在翻译一套什么结构。OpenRTB 2.5 不是一篇散文它是一组层级分明的数据模型请求从 BidRequest 根节点展开里面有 imp、site/app、device、user、regs 这些子树响应则从 BidResponse 进入 seatbid 列表每个 seat 再挂 bid。翻译时如果把层级打散按段落顺序逐句翻最后得到的文档没法用。2.1 BidRequest 里必须直译但容易误译的字段BidRequest 根节点上有几个高频字段英文原义看着简单翻成中文时却经常带偏团队对协议的理解。我整理过一张对照表直接作为翻译文档的附录比放在正文里更实用字段英文原义推荐译文注意事项impimpression 的缩写展示机会列表不要翻成“印象”或“曝光次数”它表示一次可竞价的广告位请求bidfloor最低出价最低出价CPM单位必须保留协议里是 CPM不是分、厘这种货币小单位bidfloorcur出价货币出价币种默认 USD按 ISO 4217 传app / site应用 / 网站应用媒体 / 网站媒体一个请求里只能出现其一翻译文档要标出这个互斥关系bundle应用包名应用包名不要翻成“捆绑包”iOS 传 bundle IDAndroid 传包名wseat / bseat白名单 / 黑名单席位席位白名单 / 席位黑名单2.5 里明确支持这两个字段列表元素是买方 seat IDbadv / bcat / battr三组屏蔽条件域名黑名单 / 内容分类黑名单 / 素材属性黑名单分别限制广告主域名、IAB 内容分类、创意属性三层含义不同tmax出价超时出价超时毫秒单位是 msDSP 要在这个时间内返回最容易翻错的是 imp。英文规范里 imp 全称 impression中文技术圈经常把它当成“曝光量”来说但在 OpenRTB 2.5 的语境下一个 imp 对象代表一次可竞价的展示机会里面保存着 banner、video、native 这些具体的广告位描述。翻译文档里不把 imp 翻成“曝光”联调时就不会出现“这个曝光到底要不要回 price”的争论。badv、bcat、battr 是三组容易混在一起的字段。域名黑名单对应广告主的落地页域名内容分类黑名单对应 IAB 内容分类编号素材属性黑名单对应的是创意类型例如音频自动播放、插屏这类属性。翻译文档里如果把三组字段都笼统叫“黑名单”DSP 那边就没法判断到底要过滤哪一层。我见过一个需求方把自己网站域名写进 badv还问为什么广告不返回这属于字段语义的错位。所以中文翻译文档表头的“屏蔽维度”这一列必须单独写清楚。2.2 BidResponse 与 SeatBid 层级翻译顺序决定了文档组织方式响应侧的结构严格说有三层BidResponse 根节点、seatbid 列表、每个 seat 内部的 bid 列表。很多翻译文档把 seatbid 和 bid 字段揉在一张表里读起来像是平板对象实际报文却是嵌套 JSON。翻译文档的组织顺序我建议按层级展开每层单独一章第一层BidResponse 根节点。字段有 id、seatbid、bidid、cur、customdata、nbr。其中 id 对应请求里的 id必须原样回填cur 默认 USD和请求里的 cur 保持匹配。这一层的翻译重点是让读者理解“price 是回给 exchange 的不是展示给用户的”。第二层SeatBid。字段有 seat、bid、group、ext。翻译时最容易出错的是 seat。seat 在协议里代表 DSP 内部的一个席位标识可以理解成广告主账号或投放策略的代号英文原意是席位。有翻译版本直接写成“座位”联调时双方都在对 seat 参数沟通成本立刻上升。更合理的译文是“买方席位”首字母保持 seat 原词不翻译让读者在报文里能认出这个 key。第三层bid 对象。字段有 id、impid、price、adid、nurl、burl、lurl、adm、adomain、bundle、iurl、cid、crid、tactic、dealid、w、h、api、attr、language、wlang、cat、exp、ext。翻译时要特别留意两个带 url 结尾的字段nurl 是展示通知地址竞拍成功后由 exchange 调用burl 是计费通知地址。这两个字段经常被翻译成“通知链接”或“回调地址”一旦混用做误打扰配置时就会找错位置。2.3 枚举与无值约定翻译文档最难的部分OpenRTB 2.5 里到处都是枚举值例如 at 表示拍卖类型1 代表第一价格、2 代表第二价格、3 代表协议价格api 表示 API 框架1 是 VPAID 1.0、2 是 VPAID 2.0、3 是 MRAID-1、4 是 ORMMA、5 是 MRAID-2attr 表示创意属性1 到 17 分别对应音频自动播放、全景、插屏等。这些枚举值我只保留英文原文中文字段名作为注释不参与回传。为什么枚举不翻因为线上报文里传的是数字翻译后的文字只是给人看的。图纸上把 attr 的“10”解释成“全屏/插屏”代码里仍然传 10不存在歧义。真正的问题出在有人把枚举值翻译成中文后直接写进了文档里的代码示例后接的人照抄中文对着服务端传值服务端当然不认识。所以翻译文档里凡是会出现下线上报文的地方要么保留英文枚举要么在首次出现的中文译法后面用括号标注原始枚举值。这一条放在文档头部做全局说明。无值约定同样需要单列一节。OpenRTB 2.5 里“字段不存在”和“字段为 null”和“值为 0”是三种不同语义。例如插屏广告位banner 对象里的 w、h 如果缺失表示该广告位不要求固定像素w 等于 0 则表示请求通配尺寸。翻译文档必须有专门的“空值语义表”把“缺省”“空数组”“显式传 0”逐字段标注否则新手会把所有没值的情况统一当成“没传”。3. 从术语表到排版一份能落地复现的 OpenRTB 2.5 翻译文档怎么做翻译文档要可用不能只靠翻译得准。组织方式、术语表、排版格式都会影响团队日常检索效率。这一章讲我实际采用的落地流程以及一套用于术语一致性检查的脚本思路。3.1 先定术语表再建正文术语表至少包含这四列我第一版翻译文档直接翻正文结果翻到 imp 的时候用“展示机会”翻到 impression 的时候用“曝光”同一份文档前后术语不自洽。第二版我改了流程先花一个下午建术语表再翻正文。术语表至少包含四列英文术语、推荐译文、保留原文选项、备注。所谓“保留原文选项”是标记那些建议不翻译的词例如 imp、seatbid、bidfloor、adomain、ext这些词要么是 JSON key 本身要么在表格字段名里需要被检索到。术语表示例英文术语推荐译文是否保留原文备注bid request竞价请求同时保留指代整个请求对象impression / imp展示机会imp 保留一次可竞价的广告展示bid floor最低出价bidfloor 保留单位 CPMseat买方席位seat 保留DSP 在 exchange 的标识creative创意素材creative 保留不要翻成“创意文案”win notice / nurl展示通知地址nurl 保留竞胜后调用billing / burl计费通知地址burl 保留计费用不提供给展示表格里的“是否保留原文”列是用来约束排版规范的。凡是标了保留原文的正文里首次出现时写成“展示机会imp”之后统一用“imp”。这样读者既能理解中文含义回到报文里也能找到对应 key。3.2 按对象分组翻不按章节翻英文原版 OpenRTB 2.5 是按“Object Model”章节组织的但它内部详细定义了若干对象比如 3.2.5 的 Banner 对象、3.2.6 的 Video 对象。我翻译时没有按照章节顺序从头翻到尾而是先列对象清单然后每个对象一个文档片段。这样的好处是一个广告位请求里 banner 和 video 是互斥的把它们分开翻读者查找时只需定位到对应小节。步骤可以按以下顺序执行第一步拆对象清单。从原版目录里提取所有对象名例如 BidRequest、Impression、Site、App、Device、User、Banner、Video、Native、Publisher、Content、Producer、Deal、BidResponse、SeatBid、Bid、Source、Regs。第二步逐对象翻译。每个对象单独一个表格左侧字段名中间英文定义原文摘录右侧中文翻译。定义原文必须摘录不能省略因为翻译文档的价值在于对照而不是转述。第三步枚举表单独成册。把 at、api、attr、battr、nbr、coppa 等枚举值汇总到一个附录不做正文内嵌。这样翻译文档作为排错工具时打开附录就能查到数字对应的含义不必在整个文档里反复翻找。第四步通读对齐。从头到尾读一遍翻译稿核对三件事术语表有没有漏登记的词、必填字段有没有标出、计量单位有没有丢。3.3 用脚本做术语一致性校验30 行 Python 查漏术语一致性靠人眼检查不现实我会在翻译文档的 GitHub 仓库里放一个简单的 Python 脚本每次更新文档后跑一遍把未登记的英文术语标记出来。脚本逻辑并不复杂用正则提取文档里出现的英文单词再和术语表里的英文列比对。import re from pathlib import Path # 翻译文档路径与术语表路径 doc_path Path(./openrtb_2.5_zh.md) term_path Path(./terms.csv) # 读取术语表英文术语在每行第一列 terms set() with term_path.open(encodingutf-8) as f: for line in f: term line.strip().split(,)[0].strip() if term: terms.add(term.lower()) # 提取文档中的英文单词按首字母大写或全小写过滤 def extract_words(text): return re.findall(r[a-zA-Z][a-zA-Z0-9_\-\.]*, text) full_text doc_path.read_text(encodingutf-8) words set(extract_words(full_text)) # 全小写后比对忽略常见连接词 ignore {and, the, for, with, from, are, not, you, that, this, may} unregistered sorted(w for w in words if w.lower() not in terms and w.lower() not in ignore) print(f未登记术语数{len(unregistered)}) for w in unregistered: print(w)这个脚本不复杂import re 处理正则匹配term_path 指向术语表 CSVextract_words 函数把文档里的英文单词全部抽出来。比对时做了一次全小写归一化这样“Seat”和“seat”不会算成两个词。ignore 集合里放的是连接词和常见虚词避免把“the”这种词当成漏翻术语报出来。脚本输出的是未登记英文术语列表跑完以后人工判断是新增字段没进术语表还是正文里不小心混入了原版摘要词。我实际跑第一轮排雷出来十几个词大部分是原版正文里摘录的定义例句不影响术语表完整度但也确实暴露了两个字段名没登记wlang 和 bseat。这两个词如果登记进术语表后续翻译就不会出现“wide language”这种理解偏差。4. 翻译 OpenRTB 2.5 绕不开的坑现象、原因、对策翻译文档做出来容易做出来能用是另一回事。我在两轮翻译和后面大半年的存量文档维护里遇到这么几个反复出现的坑每条都按现象、原因、解决三段记录。4.1 seat 翻成“座位”联调时两边对不上现象文档里写“座位 ID 在响应中返回”后端拿着报文找“座位 ID”对应的 key找不到。原因seat 在英文本义里确实是座位但在 OpenRTB 2.5 上下文里它指 DSP 在 AdExchange 上的席位标识。直译成“座位”会让人把注意力放到 seat 单词本身的词义上而忽略它作为结构字段名的属性。解决翻译文档的推荐译法改为“买方席位seat”并在术语表里注明“seat 是一个不透传的字符串由 DSP 自定义exchange 只做转发”。正文里第一次出现时写“seat买方席位”后续统一保留 seat不再参与翻译。4.2 price 单位丢了钱数差一千倍现象接入方把 price 理解成“价格”直接在文档示例里填 300结果竞拍成交后结算金额差 1000 倍。原因OpenRTB 2.5 定义 price 是浮点型 CPM 价格以美元计。英文原版没有强调这个单位翻译时如果只写成“价格”读者很容易把它当成单次展示的价格纸币单位。解决所有金额相关字段后面强制附加单位注释例如“pricefloatCPM单位 USD”。我甚至在翻译文档头部加了一行加粗警示“所有价格字段单位均为 CPM不是单次展示价”。这一条不算过度设计因为程序化交易接入时最贵的错误就是金额差单位。4.3 枚举值被翻译后回传服务端无法识别现象运营同学照着翻译文档里“创意属性10 全屏/插屏”的描述配置投放实际跑量时发现返回全屏素材全部报错。原因attr 字段真正传到服务端的值是 10翻译文档里的中文只是对 10 的解释。如果配置系统中直接回填了中文描述服务端解析枚举时对不上。解决翻译文档里凡是枚举字段一律保留“数字 中文注释”的写法例如“10 fullscreen / 插屏全屏”禁止把中文注释作为可回填值单独展示。团队配置系统如果支持注释字段注释写中文值必须写数字。这一条我写进了文档维护规则。4.4 ext 被当成标准字段解释扩展语义被“过度翻译”现象开发按翻译文档里的“ext 表示扩展字段常见用途包含流量质保标识”去实现结果只兼容了某一家 exchange 的私有扩展。原因OpenRTB 2.5 里的 ext 是开放字段每个平台可以自定义内部结构。翻译文档如果对 ext 补充了具体案例容易被当成标准要求。解决翻译文档里所有 ext 统一标注“扩展保留字段具体内容由接入双方协商与 OpenRTB 2.5 核心规范无关”。原版里如果某个对象对 ext 有规范注释翻译时保留原文注释并在开头声明“此类内容不作为字段定义”。4.5 native 翻成“本地”原生广告语义错位现象文档标题出现“本地广告”研发以为是指设备本地缓存的广告对接时一直找不到 native 广告位。原因native advertising 在中文广告行业里通称“原生广告”即广告形式与周围内容融合的样式。native 这个词容易联想到“本地的”翻译时如果按字面理解就会造成术语错位。解决native 在术语表里直接锁定为“原生native”备注写“指原生广告样式与地理位置、设备本地无关”。相关字段 native.request、native.ver 的翻译统一使用“原生请求”“原生版本”。4.6 必填字段和条件必填字段一视同仁排错无从下手现象翻译文档把 imp、site 等字段全部标成“必填”结果有人组请求时漏传 site.publisherexchange 也能正常接收于是怀疑文档写错了。原因OpenRTB 2.5 里字段确实分 several 类必填、条件必填、可选。条件必填的意思是“某些条件下必须出现”。site 是必填没错但 site.publisher 的必填条件取决于具体 exchange 的需求原版注释里写的是“Recommended”不是“Required”。解决翻译文档中每个字段标签只保留三档Required必填、Recommended推荐、Optional可选。条件必填字段单独在表格下方写“条件说明”不再单独设标签。这样不会造成“标了必填却没强制”的误会。5. 把翻译文档当排错手册用字段清单反推接入问题翻译文档真正发挥作用的场景是排错。联调时双方都在看同一份文档用不着现场翻原版英文规范。我实际使用下来翻译文档可以从三个维度支持排查必填字段清单、枚举值对照、字段层级定位。5.1 用必填字段表建立接入自查清单我建议翻译文档在附录放一张“必填字段快速表”按对象分组列出所有 Required 和 Recommended 字段。这个表可以直接当自查清单用对象字段必填级别常见遗漏现象BidRequestidRequired接不上响应bid 对不上请求BidRequestimpRequired空请求无广告位BidRequestapp / siteRequired二选一两种媒体同时存在或都没有BidRequestdeviceRecommended设备信息缺失影响定向BidRequestregsOptionalGDPR / COPPA 相关协议位缺失BidRequesttmaxOptional超时设置不合理返回慢BidRequestwseatOptional指定了席位白名单但对方没传BidResponseidRequired响应关联不上请求BidResponseseatbidRequired返回了空响应却没有 nbrBidResponsecurRecommended币种默认 USD和请求不一致这张表看起来简单排错时非常顶用。有次渠道反馈 DSP 返回的响应总是被 exchange 拒掉我拿这张表对了一遍发现 DSP 在 BidRequest 里传了 wseat 白名单但 exchange 那边的席位 ID 大小写不一致导致请求到达后 DSP 没有可出价的席位。单纯看文档字段描述发现不了这个问题只有把 wseat 的定义和“席位 ID 区分大小写”的备注读进去才能定位。5.2 三个真实场景的“对拍”示例场景一DSP 返回“bad request”exchange 拒绝响应。排查时先看 BidResponse 根节点id 是否等于请求的 id再看必填字段seatbid 是否缺失如果 seatbid 存在但 bid 列表为空查看响应里有没有带 nbr 字段。nbr 的枚举值会直接告诉你 no-bid 的原因例如 0 表示未知、1 表示技术错误、2 表示无效请求。翻译文档里 nbr 枚举表就承担了这个定位功能。场景二广告返回了但价格不符合预期实际扣费大于出价。对拍步骤是先确认 price 单位是不是 CPM再确认请求里的 bidfloor 是不是 CPM最后确认 at 拍卖类型。如果 at 是 1第一价格扣费就等于出价如果 at 是 2第二价格扣费可能小于等于出价。翻译文档里 at 枚举表标注了三种模式的区别比翻原版更快。场景三原生广告的请求参数缺失导致返回不了原生素材。定位时用字段层级表先确认请求里 imp 对象的 native 字段是否存在再确认 native.request 是否是符合 Native Ad Specification 的 JSON 字符串。OpenRTB 2.5 中 native 的 request 是一个经 URL 编码的 JSON 字符串翻译文档里必须把这个“双重转义”标注出来。常见做法是提醒读者native.request 是字符串里面是 JSON需要先解码再解析。5.3 用英文原文建立索引解决中文文档检索不到的情况翻译文档有一个天然弱点读者回看报文时看到的是英文 key而不是中文译名。所以我习惯在文档最后做一个“英文 key 到中文小节”的索引表adomain → 广告主域名见 2.2burl → 计费通知地址见 2.2 第三层wlang → 可接受语言列表impid → bid 关联的 imp 标识。这个索引表直接调用翻译文档里的小节编号配合目录就能快速定位。索引的意义在于当研发在日志里看到一段 JSON想查某个字段是什么含义时不需要搜索整个文档直接打开索引页一行就能跳转。这套做法让翻译文档更像开发工具而不是阅读材料。6. 回译测试和版本维护让翻译文档活下来的两个习惯翻译文档不是一次交付就结束的东西维护方式决定了它长期可用还是变成一堆过期文字。我验证翻译质量用回译测试找两名读过原版、但没参与翻译的同事拿中文译文尝试回译成英文重点回译字段名和枚举值描述。翻得回来的说明术语统一翻不回来的段落就是模糊表达需要返工。回译测试不需要全文档跑抽最常被检索的 30 个字段就足够暴露绝大部分问题。版本维护方面我习惯把翻译文档放进 git 仓库每次更新提交时在 commit message 里记录对照的英文原版版本号和 diff 来源。原版 OpenRTB 2.5 是固定版本理论上不会变但 IAB 后来发布的补充规范或解读文章会影响我们对某些字段的理解这些补充结论应该另开一节“团队补充说明”不混进核心翻译部分。半年回看一次清理掉被误用的表达保留已经被团队验证过的说法。最后一条习惯在文档头部写一句“译文以英文原版为准本翻译文档用于团队内部沟通和排错”。这句话不是免责声明它提醒每一位使用者翻译文档是工具不是标准本身。希望帮到你。本文还有配套的精品资源点击获取
