Skip to main content

AI 翻译开发接入指引

1. 接入前准备​

1.1 前提条件​

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

1.2 接入方式选择​

接入方式适用场景接入特点
SDK 接入（推荐）业务已接入 Player Network SDK，客户端可直接调用 SDK 能力。开发链路较短，适合游戏内实时功能。
API 接入仅接入 AI 翻译服务，或由游戏后端统一代理调用。便于统一鉴权、限流、日志审计和业务封装。

2. 管理端操作​

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

AI 翻译功能初始化入口

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

通过场景切换获取 gameCode

  1. API 接入时，进入「项目信息」选择「AI翻译」，在「IP白名单」中填写游戏后端出口 IP，点击保存。

AI 翻译 API 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 拼接使用。

环境后台调用域名完整调用地址
test 环境http://translator.ai-test.levelinfinite.comPOST http://translator.ai-test.levelinfinite.com/api/v1/translator
正式环境http://translator.ai.levelinfinite.comPOST http://translator.ai.levelinfinite.com/api/v1/translator
项目说明
接口路径POST <API域名>/api/v1/translator
Content-Typeapplication/json
AuthorizationBearer <token>
鉴权方式JWT，签名算法 HS256；payload.data.account 必须等于请求体 appId；payload.exp 为 Unix 秒级过期时间。
能力说明支持批量文本翻译、自动源语种、术语/短语锁定、翻译缓存与多策略翻译兜底。

3.3 请求参数​

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

context 参数​

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

3.4 JWT Token 生成要求​

  • 使用管理员分配的 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 请求示例​

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": ""
}

3.6 响应处理​

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

Content 字段​

字段类型说明
textstring原文。
outputstring翻译结果。
idstring内容 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类型常见原因处理建议
0Success调用成功。返回 result.output。
1service codec Unmarshal参数类型错误，如 string 被传为 int。检查请求 JSON 序列化与字段类型。
1001ParamsErrorappId 不存在、语种不支持、text 为空或超过批量上限、traceId 超长。校验参数；将错误和 traceId 记录到日志。
1002ServiceInternalError服务内部错误。短暂重试；多次失败联系 PNT 支持并提供 traceId。
1003PermissionErrortoken 缺失、过期、签名错误，或 token appId 与请求体不一致。重新生成 token；检查 appId/secret。
1007rate limit reachedQPM 或日 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；若由后端统一下发，客户端启动时同步配置。
  3. 构造 INTLTranslatorReq 请求结构体，填入源语种、目标语种、待翻译文本、上下文和 traceId。
  4. 调用 SDK 已封装的翻译接口提交请求。实际方法名以当前 SDK 版本文档为准。
  5. 在 INTLTranslatorResult 回调中读取 translatorResp，并解析 translator_rsp.result[].output。
  6. 对 retCode 非 0 或 SDK 基础错误码做兜底展示，并上报 traceId。

4.2 INTLTranslatorReq 字段说明​

字段类型必填说明填写建议
SrcLangstring是原始语言，默认 auto。玩家输入语言不明确时传 auto。
TargetLangstring是目标语言。建议使用玩家当前界面语言或目标接收方语言。
TranslateTextsstring是翻译内容，格式为 JSON 数组字符串，最多 5 组。例如 ["hello", "world"]，注意不是数组对象。
Topicstring否翻译文本背景信息。可填 game_chat、notice、support_ticket 等。
PastConversationstring否历史对话内容。用于对话上下文连续翻译。
Remarkstring否其他补充信息。可填角色名、装备名、术语说明。
NoCachebool否是否禁用缓存，默认 false。对实时聊天一般使用 false；特殊动态文本可设 true。
GameCodestring否，建议传AI 翻译服务为游戏分配的 gameCode。使用管理端场景切换获取的值。
ExtInfostring否扩展 JSON 字段，注意是 JSON 字符串。例如 {"scene":"chat"}。
TraceIdstring否，建议传唯一请求 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
gameCodeSDK/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 / 1003token 缺失、过期、签名错误，或请求体 appId 与 token account 不一致。重新生成 token；检查 secret；确认 Authorization: Bearer <token> 格式。
AI 翻译返回 ParamsError / 1001appId 不存在、语种不支持、text 为空或超过限制。检查 appId、srcLang、targetLang、text 数量和长度；保留 traceId 便于排查。
SDK 回调提示 Invalid param, openid or token empty客户端未登录或未从 authResult 获取 openId/token。重新登录，确认 SDK 登录态有效后再调用。
SDK 回调 invalid config / ret 91002后台配置缺失。联系 Player Network 助手补充配置。
限流错误 1007QPM 或日 PV 达到硬限流。业务侧降级或提示稍后重试；联系管理员调整限流配置。
客户端常见异常

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

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

附录：后端接入伪代码​

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

import jwt
import requests

app_id = "<app-id>"
secret = "<secret>"
api_url = "https://<api-domain>/api/v1/translator"

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",
    },
)
print(resp.json())
Last updated on
隐私政策用户协议数据处理协议开源许可协议
©2025 Proxima Beta Pte. Ltd. All rights reserved.