宠物档案语言与 locale
locale 是请求级展示语言,不会永久写入宠物档案。它只影响平台已本地化的展示字段;当前明确为 breed_display_name。
当前支持的语言
目前宠物档案仅支持以下两种语言:
zh-CN(简体中文,默认)en-US(英文)
规则速览
| 规则 | 说明 |
|---|---|
| 默认值 | zh-CN。 |
| 当前支持语言 | 仅支持 zh-CN(简体中文)与 en-US(英文)。 |
| 格式要求 | 完整 BCP 47:语言小写、区域大写(如 zh-CN、en-US)。 |
| 仅格式正确不够 | 语言必须在当前环境启用;使用 breed_code 时,该品种还必须已有该语言翻译。 |
| 不静默回退 | 传入不支持语言或缺翻译时返回业务错误,不会自动回退为中文,也不会返回空展示名。 |
| 不自动翻译 | name、pet_variety、扩展记录的 title / content 等调用方提交的原始业务文本保持原样。 |
支持 locale 的接口
| 接口 | 作用 |
|---|---|
POST /pet-profiles?locale=... | 创建后按该语言返回 breed_display_name。 |
GET /pet-profiles?locale=... | 列表中的品种展示名本地化。 |
GET /pet-profiles/{pet_profile_id}?locale=... | 详情中的品种展示名本地化。 |
PATCH /pet-profiles/{pet_profile_id}?locale=... | 更新后按该语言返回品种展示名。 |
调用示例
示例基于同一份档案(网关基础 URL 为 https://open-api.habitaxx.com/v1/ms-ai-fast):
json
{
"id": 44,
"name": "团子",
"pet_type": 2,
"breed_code": "dog.shiba-inu",
"pet_variety": "柴犬",
"weight": "10.10kg"
}1. 简体中文 GET /pet-profiles/44?locale=zh-CN
json
{
"code": 200,
"message": "success",
"data": {
"id": 44,
"name": "团子",
"pet_type": 2,
"breed_code": "dog.shiba-inu",
"breed_display_name": "柴犬",
"pet_variety": "柴犬",
"weight": "10.10kg",
"locale": "zh-CN"
}
}2. 英文 GET /pet-profiles/44?locale=en-US
en-US 格式正确,且该品种已有英文翻译时:
json
{
"code": 200,
"message": "success",
"data": {
"id": 44,
"name": "团子",
"pet_type": 2,
"breed_code": "dog.shiba-inu",
"breed_display_name": "Shiba Inu",
"pet_variety": "柴犬",
"weight": "10.10kg",
"locale": "en-US"
}
}name: "团子" 与 pet_variety: "柴犬" 保持原样:需要多语言宠物昵称或自定义品种文本时,由接入方维护对应业务字段,不要依赖 locale 自动翻译。
常见错误与处理
| 情况 | 示例 | 处理 |
|---|---|---|
| 语言格式错误 | zh-cn、en-us | 返回格式校验错误;按 BCP 47 大小写修正后重试。 |
| 语言不支持 / 未启用 | 传入 zh-CN 与 en-US 以外的语言 | 返回业务错误;不要期待自动回退到 zh-CN。 |
| 品种缺翻译 | 传入 en-US,但该 breed_code 尚无英文翻译 | 返回业务错误;补齐翻译后再调用。 |
| 期望用户文本被翻译 | name、pet_variety、title、content | 不翻译,始终返回调用方提交的原值。 |