获取支持的资料语言¶
请求参数¶
供注册和编辑资料中的“我会的语言/我想学习的语言”选择器使用,两处使用同一目录。当前每个资料字段各选择一种语言。本接口不配置App界面翻译支持范围,也不修改用户资料。
八项公共请求头全部必填,X-Client-Type=app,平台ios/android。无需Authorization,若主动携带则仍校验凭证。无路径参数、查询参数和业务请求体,一次返回全部条目,不分页。
Accept-Language决定name及成功/错误提示,支持中文、英文、日文、韩文及地区变体;缺省或不支持时回退英文,每次同时返回完整四语names。JSON遵循AES/JWE,生产要求HTTPS和JWE,加密GET的信封放入X-Budyoo-JWE;当前固定码dev允许明文HTTP联调。合法请求ID回传X-Request-Id,响应Cache-Control: no-store。
请求示例¶
base_url='https://api.budyoo.cn' # 当前dev,生产使用HTTPS及JWE
device_id='4d4ae3ea-6a4a-4f34-a292-8e94551851d7' # 同一安装持久保存
curl --fail-with-body "$base_url/api/v1/catalogs/languages" \
-H 'Accept: application/json' -H 'Accept-Language: zh-CN' \
-H 'X-Client-Type: app' -H 'X-Platform: android' \
-H 'X-App-Version: 1.0.0' -H 'X-App-Build: 1' -H 'X-Channel: dev' \
-H "X-Device-Id: $device_id" \
-H "X-Request-Id: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
-H "X-Request-Timestamp: $(date +%s)000"
成功响应¶
HTTP200。示例只截取首项,实际返回当前支持的10种资料语言。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"version": "2026-11-03.2",
"language": "zh-CN",
"sort": "POPULARITY",
"rankingSource": "CONFIGURED",
"languages": [
{
"id": "zh",
"name": "中文",
"names": {"zh-CN":"中文","en":"Chinese","ja":"中国語","ko":"중국어"},
"nativeName": "中文 / 汉语",
"symbol": "中",
"sortOrder": 1,
"popularityRank": 1,
"aliases": ["中文","Chinese","中国語","중국어","中文 / 汉语","汉语","普通话","Mandarin"]
}
]
},
"errors": []
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| version | string | 否 | 语言目录的数据版本;配置名称、顺序、条目或别名变化时更新 |
| language | string | 否 | 显示名称实际语言,zh-CN/en/ja/ko |
| sort | string | 否 | 当前POPULARITY,按热门排名返回 |
| rankingSource | string | 否 | 当前CONFIGURED,排名来自服务端预设热门优先级,不代表实时用户统计 |
| languages | object[] | 否 | 支持的完整资料语言目录,两种语言选择器共用 |
| languages[].id | string | 否 | 稳定小写语言代码,保存到spokenLanguage/learningLanguage |
| languages[].name | string | 否 | 当前界面语言的显示名称,例如英文下中文显示Chinese |
| languages[].names | object | 否 | 固定含zh-CN/en/ja/ko四个非空string值 |
| languages[].nativeName | string | 否 | 语言自身名称,例如Español、العربية,不随界面语言变化 |
| languages[].symbol | string | 否 | 现有文字标记,例如中、A、日、한;不是图片或国旗URL |
| languages[].popularityRank | integer | 否 | 唯一正整数,数值越小越靠前;服务端已按此值升序返回 |
| languages[].sortOrder | integer | 否 | 兼容字段,始终等于popularityRank;客户端直接保留数组顺序即可 |
| languages[].aliases | string[] | 否 | 搜索别名,可与id/name/names/nativeName合并搜索 |
当前预设热门顺序为:中文zh、英语en、日语ja、韩语ko、西班牙语es、法语fr、葡萄牙语pt、德语de、阿拉伯语ar、印地语hi。当前热门优先级沿用已确认UI,由服务端统一配置;尚未按用户选择次数、注册人数或活跃度自动计算,不宣称全球语言热度榜。客户端直接使用返回数组,禁止按英文、名称、代码或本地默认规则重新排序;切换界面语言、渠道或国内/海外地区不改变顺序。
失败响应¶
| HTTP | code | 原因与处理 |
|---|---|---|
| 400 | INVALID_CLIENT_HEADERS | 公共头缺失、重复、格式错误或客户端/平台组合不符 |
| 400 | ENCRYPTION_REQUIRED/INVALID_ENCRYPTED_REQUEST | 正式缺少JWE或密文认证失败,其他加密错误见公共协议 |
| 401 | UNAUTHORIZED | 主动携带的凭证无效或格式不正确 |
| 403 | FORBIDDEN | 合法元数据的调用端为admin,非App |
| 426 | HTTPS_REQUIRED | 当前模式要求HTTPS却使用明文HTTP |
错误格式见公共协议,提示按请求语言生成,字段错误使用errors[].field/message。
{"code":"INVALID_CLIENT_HEADERS","message":"客户端请求头校验失败。","data":null,"errors":[]}
接入说明¶
- 直接使用服务端
name/names显示,不依赖客户端auth_language_name_*固定键;新增语言代码也应能展示。原生名称建议按文字自身方向排版,阿拉伯语无需客户端翻译。 - 语言标记用返回的
symbol文字。一个语言可对应多个国家,本接口不绑定某一国家国旗、不提供图片下载入口。 - 确认选择后只保存
id。注册使用保存注册草稿,注册完成后使用保存本人资料,分别写入spokenLanguage或learningLanguage。例如中文保存zh,不能误传界面语言标签zh-CN。 - 旧注册字典继续返回原
languages[].id/native/symbol格式;后端独立目录、旧字典、后台资料字典和资料字段校验共用同一份配置。旧客户端可继续使用;新选择器改用本独立接口,兴趣改用完整兴趣目录,旧字典只保留兼容代码。 - 版本
2026-11-03.2将sort由CONFIGURED明确为POPULARITY,新增rankingSource=CONFIGURED和popularityRank;原sortOrder继续保留且值一致。先前客户端尚未接入本独立接口,接入时按新契约解析;缓存按version变化更新。 - 目录来自服务端随版本发布的配置,启动校验唯一代码/顺序、完整四语及非空原生名称/标记。当前未实现后台动态增删语言或热度管理。修改配置并发布后生效,不能把静态配置当成已实现管理API。
- App界面语言当前仍只有中英日韩四种,由现有界面语言设置管理;资料目录中的十种语言不意味着界面支持十种翻译。
当前热门排名契约已部署,通过312项整合Java回归,新增乱序配置测试证明输出以popularityRank为准且sortOrder保持同值。公网六组四语/缺省/未知语言响应验证version=2026-11-03.2、sort=POPULARITY、rankingSource=CONFIGURED、所有排名及名称,旧注册字典兼容通过。Flutter语言选择器尚未迁移到本接口,需按新契约接入;旧客户端仍通过注册字典获取代码并使用本地翻译。资料语种及App界面语言范围保持现有定义。