GET/api/v1/catalogs/languages
匿名,需App公共头JSON 响应接入指南 ↗

获取支持的资料语言

请求参数

供注册和编辑资料中的“我会的语言/我想学习的语言”选择器使用,两处使用同一目录。当前每个资料字段各选择一种语言。本接口不配置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界面语言范围保持现有定义。