AI 翻译开发接入指引

1. 接入前准备

1.1 前提条件

• 已注册 Player Network 控制台，并完成业务项目创建。
• 若采用 SDK 接入，客户端 Player Network SDK 版本需为 1.32 及以上。

1.2 接入方式选择

接入方式	适用场景	接入特点	安全注意事项
SDK 接入（推荐）	业务已接入 Player Network SDK，客户端可直接调用 SDK 能力。	开发链路较短，适合游戏内实时功能。	客户端只使用 SDK 所需参数，不应保存 secret。
API 接入	仅接入 AI 翻译服务，或由游戏后端统一代理调用。	便于统一鉴权、限流、日志审计和业务封装。	secret 仅保存在可信后端或密钥管理系统中。

2. 管理端操作

2.1 功能入口

首次进入 翻译内容管理，点击「立即免费体验」完成 AI 翻译功能初始化。

2.2 获取参数

• 点击右上角「场景切换」，获取本次业务场景对应的 gameCode。SDK/API 调用时均建议传入该 gameCode。

• API 接入时，前往「项目信息」选择「AI 翻译」，在「API 参数」区域获取 APPID（appId） 和 AppSecret（secret），用于签发请求鉴权所需的 JWT Token。具体要求见「3.4 JWT Token 生成要求」。

2.3 白名单配置

API 接入时，在「项目信息 → AI 翻译」的「IP 白名单」区域填写游戏后端出口 IP，确认无误后保存。

3. 后台 API 接入

3.1 调用链路

1. 客户端或业务服务向游戏后端提交待翻译文本、源语种、目标语种、业务场景等信息。
2. 游戏后端使用 appId + secret 生成 JWT Token，并调用 AI 翻译 API。
3. AI 翻译服务返回 retCode、message、result；后端按业务需要返回给客户端或写入业务系统。
4. 后端记录 traceId、openId、gameCode、srcLang、targetLang、retCode 等关键字段，便于问题定位。

3.2 接口信息

后台调用 AI 翻译 API 时，请根据当前部署环境选择对应服务域名，并与接口路径 /api/v1/translator 拼接使用。

IP 白名单

调用接口前，需要在 Player Network 管理端配置游戏后端出口 IP 白名单，否则接口无法成功调用。配置方式请参考「2.3 白名单配置」。

环境	后台调用域名	完整调用地址
test 环境	http://translator.ai-test.levelinfinite.com	POST http://translator.ai-test.levelinfinite.com/api/v1/translator
正式环境	http://translator.ai.levelinfinite.com	POST http://translator.ai.levelinfinite.com/api/v1/translator

项目	说明
接口路径	POST <API域名>/api/v1/translator
Content-Type	application/json
Authorization	Bearer <token>
鉴权方式	JWT，签名算法 HS256；payload.data.account 必须等于请求体 appId；payload.exp 为 Unix 秒级过期时间。
能力说明	支持批量文本翻译、自动源语种、术语/短语锁定、翻译缓存与多策略翻译兜底。

3.3 请求参数

参数	类型	必填	说明
openId	string	是	用户 ID，标识具体用户。
appId	string	是	管理员分配的 appId，必须与 JWT payload.data.account 一致。获取方式见「2.2 获取参数」。
srcLang	string	是	源语种代码；不明确时可传 auto。
targetLang	string	是	目标语种代码，如 zh、en、ja、ko、ru。
gameCode	string	否，建议传	业务场景代码；为空时使用 appId 的默认 gameCode；不同场景建议分别申请。获取方式见「2.2 获取参数」。
text	[]string	是	待翻译文本列表，最多 5 条，总 token 数不超过 4096。
context	json object	否	翻译上下文，包括 topic、pastConversation、remark。
traceId	string	否，建议传	唯一请求 ID，用于请求链路追踪。
noCache	bool	否	是否跳过缓存：false 使用缓存，true 不使用缓存；默认 false。
extInfo	string	否	扩展字段，JSON string，便于后续扩展。

context 参数

参数	类型	必填	说明
topic	string	否	主题/场景，例如“游戏聊天”“活动公告”“电竞解说”。
pastConversation	string	否	历史对话上下文，可提升对话翻译一致性。
remark	string	否	额外说明，例如专有名词、角色名、语气要求。

3.4 JWT Token 生成要求

• appId 和 secret 从管理端获取，具体操作见「查看参数获取方式」；secret 仅保存在可信后端或密钥管理系统中。
• 使用管理员分配的 secret 作为 HS256 签名密钥。
• payload 必须包含 data.account，值为 appId。
• payload 必须包含 exp，值为 Unix 秒级过期时间。
• 请求头使用 Authorization: Bearer <token>。
• 请求体 appId 必须与 token 中的 data.account 一致。

JWT payload 示例

{
  "exp": 1710000000,
  "data": {
    "account": "<appId>"
  }
}

3.5 请求示例

application/json 请求示例

POST /api/v1/translator HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>

{
  "openId": "test-user-001",
  "appId": "<app-id>",
  "srcLang": "auto",
  "targetLang": "en",
  "gameCode": "<game-code>",
  "text": ["航天基地的重装甲兵"],
  "context": {
    "topic": "game chat",
    "pastConversation": "",
    "remark": ""
  },
  "traceId": "translator-20260701-0001",
  "noCache": false,
  "extInfo": ""
}

完整的 Python 调用示例见「附录：后端接入伪代码」中的“Python 后端调用示例”。

3.6 响应处理

响应字段	类型	说明	处理建议
retCode	string	返回码，"0" 表示成功。	非 0 时按错误类型返回业务兜底提示，并记录 traceId。
message	string	返回消息。	用于日志定位，前端展示需转为业务友好文案。
result	[]Content	翻译结果列表，与请求 text 顺序一致。	按 index 映射回原文本。
debugInfo	json object	默认不返回，通常为 null。	一般不透传客户端。

Content 字段

字段	类型	说明
text	string	原文。
output	string	翻译结果。
id	string	内容 ID，由 appId + srcLang + targetLang + text 计算 MD5 得到。

成功响应示例

{
  "retCode": "0",
  "message": "Success",
  "result": [
    {
      "text": "航天基地的重装甲兵",
      "output": "Cosmodrone's heavy armored soldier",
      "id": "f009a3089f293939c0f01f36c0f047e2"
    }
  ],
  "debugInfo": null
}

3.7 错误码与后端处理建议

retCode	类型	常见原因	处理建议
0	Success	调用成功。	返回 result.output。
1	service codec Unmarshal	参数类型错误，如 string 被传为 int。	检查请求 JSON 序列化与字段类型。
1001	ParamsError	appId 不存在、语种不支持、text 为空或超过批量上限、traceId 超长。	校验参数；将错误和 traceId 记录到日志。
1002	ServiceInternalError	服务内部错误。	短暂重试；多次失败联系 PNT 支持并提供 traceId。
1003	PermissionError	token 缺失、过期、签名错误，或 token appId 与请求体不一致。	重新生成 token；检查 appId/secret。
1007	rate limit reached	QPM 或日 PV 达到硬限流。	前端提示稍后重试；后端熔断或降级；联系管理员调整配额。

短语锁定说明

原文本可通过 <span class='notranslate'>{word}</span> 标记不翻译内容。调用方需要处理译文中可能返回的 <span class='notranslate'></span> 标签，避免标签直接展示给玩家。

4. 客户端 SDK 接入

版本要求

SDK 接入 AI 翻译能力需使用 Player Network SDK 1.32 及以上版本。低于 1.32 的版本不支持相关能力，需先完成 SDK 升级。

4.1 调用流程

1. 确认客户端已完成 Player Network SDK 初始化和用户登录，能获取 openId / token 等登录态信息。
2. 从管理端或后端配置中获取 gameCode；若由后端统一下发，客户端启动时同步配置。管理端获取方式见「2.2 获取参数」。
3. 构造 INTLTranslatorReq 请求结构体，填入源语种、目标语种、待翻译文本、上下文和 traceId。
4. 调用 SDK 已封装的翻译接口提交请求。实际方法名以当前 SDK 版本文档为准。
5. 在 INTLTranslatorResult 回调中读取 translatorResp，并解析 translator_rsp.result[].output。
6. 对 retCode 非 0 或 SDK 基础错误码做兜底展示，并上报 traceId。

4.2 INTLTranslatorReq 字段说明

字段	类型	必填	说明	填写建议
SrcLang	string	是	原始语言，默认 auto。	玩家输入语言不明确时传 auto。
TargetLang	string	是	目标语言。	建议使用玩家当前界面语言或目标接收方语言。
TranslateTexts	string	是	翻译内容，格式为 JSON 数组字符串，最多 5 组。	例如 ["hello", "world"]，注意不是数组对象。
Topic	string	否	翻译文本背景信息。	可填 game_chat、notice、support_ticket 等。
PastConversation	string	否	历史对话内容。	用于对话上下文连续翻译。
Remark	string	否	其他补充信息。	可填角色名、装备名、术语说明。
NoCache	bool	否	是否禁用缓存，默认 false。	对实时聊天一般使用 false；特殊动态文本可设 true。
GameCode	string	否，建议传	AI 翻译服务为游戏分配的 gameCode。	使用管理端场景切换获取的值，具体操作见「2.2 获取参数」。
ExtInfo	string	否	扩展 JSON 字段，注意是 JSON 字符串。	例如 {"scene":"chat"}。
TraceId	string	否，建议传	唯一请求 ID，用于请求-响应关联。	建议由客户端或后端生成 UUID。

客户端请求结构示例（伪代码，方法名以 SDK 实际版本为准）

INTLTranslatorReq req;
req.SrcLang = "auto";
req.TargetLang = "en";
req.TranslateTexts = "[\"航天基地的重装甲兵\"]";
req.Topic = "game_chat";
req.PastConversation = "";
req.Remark = "";
req.NoCache = false;
req.GameCode = "<game-code>";
req.ExtInfo = "";
req.TraceId = "client-trace-001";

// SDK.Translate(req, OnTranslatorResult);

4.3 INTLTranslatorResult 回调处理

• 文字翻译结果在 translatorResp 中返回，游戏侧需要自行解析。
• 优先判断 SDK 基础结果 ret / ret_code，再解析 translator_rsp.retCode。
• translator_rsp.retCode 为 "0" 时，从 translator_rsp.result[].output 获取译文。
• translator_rsp.result 与请求 TranslateTexts 中的文本顺序一一对应。

translatorResp 核心结构示例

{
  "ret": 0,
  "msg": "success",
  "translator_rsp": {
    "retCode": "0",
    "message": "Success",
    "traceId": "trace",
    "result": [
      {
        "text": "Original Text",
        "output": "Translated Text",
        "id": "c5b2802a287f58c9ce250f8c77fc6029"
      }
    ]
  },
  "asr_rsp": ""
}

5. 联调与验收

5.1 验收清单

检查项	通过标准	问题定位字段
功能初始化	管理端已完成 AI 翻译初始化。	项目 ID、appId
gameCode	SDK/API 传入的 gameCode 与管理端场景一致。	gameCode、traceId
白名单	后端出口 IP 已加入 AI 翻译 API 白名单。	出口 IP、请求时间
JWT 鉴权	Authorization: Bearer <token> 可通过鉴权。	appId、exp、traceId
参数校验	openId、srcLang、targetLang、text 等字段符合要求。	请求体、retCode、message
批量限制	单次最多 5 条文本，总 token 数不超过 4096。	text length、retCode
响应映射	result 与请求 text 顺序一致，客户端展示 output。	id、text、output
异常兜底	1001/1003/1007 等错误能正确提示和上报。	retCode、message、traceId

5.2 上线前确认

• 生产域名、白名单、限流配置已确认。
• 后端 token 过期时间合理，具备自动刷新能力。
• 日志中不打印 secret、完整 token 和用户敏感文本。
• 客户端具备翻译失败兜底文案。
• 关键错误码和 traceId 已接入监控告警或问题上报。

6. 常见问题与排障建议

问题	可能原因	解决方案
AI 翻译返回 PermissionError / 1003	token 缺失、过期、签名错误，或请求体 appId 与 token account 不一致。	重新生成 token；检查 secret；确认 Authorization: Bearer <token> 格式。
AI 翻译返回 ParamsError / 1001	appId 不存在、语种不支持、text 为空或超过限制。	检查 appId、srcLang、targetLang、text 数量和长度；保留 traceId 便于排查。
SDK 回调提示 Invalid param, openid or token empty	客户端未登录或未从 authResult 获取 openId/token。	重新登录，确认 SDK 登录态有效后再调用。
SDK 回调 invalid config / ret 91002	后台配置缺失。	联系 Player Network 助手补充配置。
限流错误 1007	QPM 或日 PV 达到硬限流。	业务侧降级或提示稍后重试；联系管理员调整限流配置。

客户端常见异常

回调返回 Invalid param, openid or token empty 时，通常是未传入 openId 或 token。请重新登录，并从 authResult 登录态中获取正确 openId/token 后再调用接口。

回调返回 "msg":"invalid config", "ret":91002 时，通常为后台配置缺失，需要联系 Player Network 助手进行配置。

附录：后端接入伪代码

app_id 和 secret 用于签发 JWT token，token 通过 Authorization 请求头用于接口鉴权。生产环境中请从安全配置或密钥管理系统读取凭据，不要将其硬编码到代码仓库。

Python 后端调用示例

Python 伪代码：生成 JWT 并调用 AI 翻译

import json
import time
import uuid

import jwt
import requests

# app_id 和 secret 从管理端获取，用于签发 JWT token。
app_id = "<app_id>"  # APPID
secret = "<secret>"  # AppSecret
api_url = "<完整调用地址>"  # 根据 3.2 接口信息选择对应环境

token = jwt.encode(
    {
        "data": {"account": app_id},
        "exp": int(time.time()) + 300,
    },
    secret,
    algorithm="HS256",
)

body = {
    "openId": "test-user-001",
    "appId": app_id,
    "srcLang": "auto",
    "targetLang": "en",
    "gameCode": "<game-code>",
    "text": ["航天基地的重装甲兵"],
    "traceId": str(uuid.uuid4()),
    "noCache": False,
    "extInfo": "",
}

resp = requests.post(
    api_url,
    json=body,
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    timeout=30,
)
resp.raise_for_status()
print(json.dumps(resp.json(), indent=4, ensure_ascii=False))