本地化 API
运行示例前,将 <APPBASE_ENDPOINT_WITH_V1> 替换为目标环境的 API 地址,并核对项目及凭据属于同一环境。
提供面向全球化业务与企业多语言工作台的本地化静态字典与地理位置解析服务:支持基于客户端请求 IP 解析国家、大洲、欧盟归属与建议货币,并提供 ISO 标准国家、大洲、电话区号、货币与语言字典清单。
服务与资源边界
Locale API 是 Agentbase 平台内置的无状态国际化(i18n)与区域元数据基础服务,服务边界与核心特性如下:
只读静态字典与 IP 归属解析:所有端点均为幂等
GET请求,不在项目数据库(OceanBaseShared V2)中产生业务表写入开销。多语言动态翻译(
X-Appwrite-Locale):调用方可通过请求头X-Appwrite-Locale(如zh-CN、en-US、ja-JP)指定响应字典中country、continent、countries[].name等显示名称的目标语言;未指定时默认使用英文(en)。与图形头像服务联动:
/v1/locale/countries返回的两位 ISO 3166-1 Alpha-2 国家代码(如CN、US)可直接传入 头像与图形 API 的/v1/avatars/flags/{code}端点渲染对应国旗图标。代理透传注意事项:当服务端作为反向代理替终端用户调用
GET /v1/locale时,ip字段反映的是发起 HTTP 请求的出口 IP(或经受信任网关转发的X-Forwarded-For客户端真实 IP)。
资源与基础路径
Base URL:
https://appbuild-sit.oceanbase.com/v1(或https://<your-endpoint>/v1)。路径前缀:
/locale;无状态端点,返回locale及各类*List静态字典模型。核心响应模型概览:
| 模型名称 | 关联端点 | 核心字段 | 说明 |
|---|---|---|---|
locale | GET /locale | ip, countryCode, country, continentCode, continent, eu, currency | 当前请求方的地理位置与区域本地化画像 |
localeCodeList | GET /locale/codes | total, localeCodes[] (code, name) | 平台支持的 ISO 639-1 / BCP-47 语言区域代码列表 |
continentList | GET /locale/continents | total, continents[] (name, code) | 七大洲代码与本地化名称列表 |
countryList | GET /locale/countries (/eu) | total, countries[] (name, code) | 全球国家/地区或欧盟成员国列表 |
phoneList | GET /locale/countries/phones | total, phones[] (code, countryCode, countryName) | 国际长途电话区号映射列表 |
currencyList | GET /locale/currencies | total, currencies[] (symbol, name, code, decimalDigits, rounding) | ISO 4217 货币符号与精度规则列表 |
languageList | GET /locale/languages | total, languages[] (name, code, nativeName) | 语言英文名与母语自称名列表 |
认证与权限
认证与请求头约定见 通用约定。
| 请求头 | 必填 | 示例值 | 说明 |
|---|---|---|---|
X-Appwrite-Project | 是 | enterprise-ai-hub-210 | 项目 ID |
X-Appwrite-Key | 服务端调用必填 | <APPBASE_API_KEY> | 项目 API Key,需具备 locale.read scope |
X-Appwrite-Locale | 否 | zh-CN | 指定返回国家、大洲名称的本地化语言代码 |
OpenAPI spec 认证标注为
Project + Session或Project + Key,所需 API Key Scope 为locale.read。
端点总览
Locale 服务共包含 8 个只读端点,分为「请求方区域探测」与「标准枚举字典」两大类:
| 分类 | 端点 | 返回模型 | 典型场景 |
|---|---|---|---|
| 请求方区域探测 | GET /v1/locale | locale | 智能客服会话初始化时自动识别访客所在时区/国家与默认语言 |
| 语言与区域代码 | GET /v1/locale/codes、GET /v1/locale/languages | localeCodeList、languageList | 控制台或客户端个人中心的语言切换下拉菜单 |
| 地理与电话区号 | GET /v1/locale/continents、GET /v1/locale/countries、GET /v1/locale/countries/eu、GET /v1/locale/countries/phones | continentList、countryList、phoneList | 手机号短信验证码登录组件(如 +86)、GDPR 欧盟合规分流判定 |
| 货币与结算规则 | GET /v1/locale/currencies | currencyList | AI 网关计费账单展示、多币种小数位与四舍五入格式化 |
端点清单
| 方法 + 路径 | Scope | 幂等性 | 用途 |
|---|---|---|---|
GET /locale | locale.read | 是 | 获取当前请求方的地理与本地化信息 |
GET /locale/codes | locale.read | 是 | 列出全部支持的 Locale 语言区域代码 |
GET /locale/continents | locale.read | 是 | 列出全部大洲代码与名称 |
GET /locale/countries | locale.read | 是 | 列出全部国家/地区代码与名称 |
GET /locale/countries/eu | locale.read | 是 | 列出当前欧盟(EU)成员国 |
GET /locale/countries/phones | locale.read | 是 | 列出各国电话区号与国家对照表 |
GET /locale/currencies | locale.read | 是 | 列出全部 ISO 4217 货币及格式规则 |
GET /locale/languages | locale.read | 是 | 列出全部 ISO 639-1 语言及母语名称 |
端点详解
多语言字典切换与缓存实践
本地化头部传递:所有
/v1/locale/*端点均识别X-Appwrite-Locale请求头。例如传入X-Appwrite-Locale: zh-CN时,GET /v1/locale/countries会将CN的name返回为本地化中文名称;若传入未知语言代码,则平滑回退到默认英文。内网与未知 IP 兜底行为:在私有化部署或容器内网调用
GET /v1/locale时,若源 IP 属于 RFC 1918 私网网段(如10.0.0.0/8、172.16.0.0/12、192.168.0.0/16)且未配置外部 GeoIP 透传头,GeoIP 库无法命中公网记录,响应中的countryCode、continentCode、currency将返回空字符串"",eu返回false,不会抛出 4xx/5xx 错误。字典缓存建议:除
GET /v1/locale依赖实时请求 IP 外,其余 7 个字典端点返回的数据仅随平台版本升级更新,服务端业务可按(endpoint, locale_header)维度在进程内缓存 24 小时。
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。
Locale
GET /v1/locale
按请求 IP 解析当前用户地理与本地化信息:国家、大洲、EU 归属与建议货币;配合 X-Appwrite-Locale 请求头可返回对应语言名称。
输入:无 path/query/body 参数(可选请求头 X-Appwrite-Locale)。
输出:返回 200 OK + locale 模型:
| 字段 | 类型 | 说明 |
|---|---|---|
ip | string | 客户端 IP 地址 |
countryCode | string | ISO 3166-1 两位国家代码(如 CN、US);内网未知 IP 时为 "" |
country | string | 国家名称(支持 X-Appwrite-Locale 本地化) |
continentCode | string | 大洲代码:AF / AN / AS / EU / NA / OC / SA |
continent | string | 大洲名称(支持本地化) |
eu | boolean | 是否属于欧盟(EU)成员国 |
currency | string | ISO 4217 三位货币代码(如 CNY、USD) |
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-H "X-Appwrite-Locale: zh-CN"
)响应示例:
{
"ip": "192.0.2.10",
"countryCode": "CN",
"country": "China",
"continentCode": "AS",
"continent": "Asia",
"eu": false,
"currency": "CNY"
}GET /v1/locale/codes
列出全部 locale 代码(ISO 639-1 / BCP-47),供前端语言下拉或 X-Appwrite-Locale 取值参考使用。
输入:无 path/query/body 参数。
输出:返回 localeCodeList(total + localeCodes[],元素含 code、name)。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/codes" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例:
{
"total": 2,
"localeCodes": [
{
"code": "en-us",
"name": "US"
},
{
"code": "zh-cn",
"name": "China"
}
]
}GET /v1/locale/continents
列出全部大洲(两位代码 + 名称,名称支持本地化)。
输入:无 path/query/body 参数。
输出:返回 continentList(total + continents[],元素含 name、code)。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/continents" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例:
{
"total": 2,
"continents": [
{
"name": "Europe",
"code": "EU"
},
{
"name": "Asia",
"code": "AS"
}
]
}GET /v1/locale/countries
列出全部国家(ISO 3166-1 两位代码 + 名称,名称支持本地化)。
输入:无 path/query/body 参数。
输出:返回 countryList(total + countries[],元素含 name、code)。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/countries" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例:
{
"total": 2,
"countries": [
{
"name": "United States",
"code": "US"
},
{
"name": "China",
"code": "CN"
}
]
}GET /v1/locale/countries/eu
列出当前欧盟成员国(结构同 /locale/countries)。
输入:无 path/query/body 参数。
输出:返回 countryList(total + countries[],元素含 name、code)。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/countries/eu" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例:
{
"total": 2,
"countries": [
{
"name": "Germany",
"code": "DE"
},
{
"name": "France",
"code": "FR"
}
]
}GET /v1/locale/countries/phones
列出各国电话区号:与国家代码对照,用于手机号输入组件与短信发送(Messaging SMS)号码前缀校验。
输入:无 path/query/body 参数。
输出:返回 phoneList(total + phones[],元素含 code(如 +1、+86)、countryCode、countryName)。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/countries/phones" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例:
{
"total": 2,
"phones": [
{
"code": "+1",
"countryCode": "US",
"countryName": "United States"
},
{
"code": "+86",
"countryCode": "CN",
"countryName": "China"
}
]
}GET /v1/locale/currencies
列出全部货币:符号、名称、复数、小数位与舍入规则,供金额格式化使用。
输入:无 path/query/body 参数。
输出:返回 currencyList(total + currencies[]):
| 字段 | 类型 | 说明 |
|---|---|---|
symbol | string | 国际通用货币符号(如 $、¥) |
name | string | 货币单数名称(如 Chinese yuan) |
symbolNative | string | 本地货币符号 |
decimalDigits | integer | 标准小数位数(如 CNY 为 2,JPY 为 0) |
rounding | number | 最小舍入步长(通常为 0) |
code | string | ISO 4217 三位大写代码(如 CNY、USD) |
namePlural | string | 货币复数名称 |
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/currencies" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例:
{
"total": 2,
"currencies": [
{
"symbol": "$",
"name": "US dollar",
"symbolNative": "$",
"decimalDigits": 2,
"rounding": 0,
"code": "USD",
"namePlural": "US dollars"
},
{
"symbol": "¥",
"name": "Chinese yuan",
"symbolNative": "¥",
"decimalDigits": 2,
"rounding": 0,
"code": "CNY",
"namePlural": "Chinese yuan"
}
]
}GET /v1/locale/languages
列出全部语言(ISO 639-1):两位代码、英文名与本地语言名。
输入:无 path/query/body 参数。
输出:返回 languageList(total + languages[],元素含 name、code、nativeName)。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "<APPBASE_ENDPOINT_WITH_V1>/locale/languages" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例:
{
"total": 2,
"languages": [
{
"name": "Italian",
"code": "it",
"nativeName": "Italiano"
},
{
"name": "Chinese",
"code": "zh",
"nativeName": "中文"
}
]
}错误与边界
| HTTP 状态码 | 错误类型 (type) | 触发原因 | 排障建议 |
|---|---|---|---|
401 Unauthorized | general_access_forbidden | 缺少 X-Appwrite-Project 或项目 ID 不存在 | 检查请求头中的项目 ID(如 enterprise-ai-hub-210) |
401 Unauthorized | general_unauthorized_scope | API Key 未授予 locale.read 权限 | 在控制台 API Key 设置中勾选 locale.read |
429 Too Many Requests | general_rate_limit_exceeded | 高频轮询静态字典触发实例限流 | 字典列表(countries/currencies/phones/languages)应缓存在应用内存中,避免按每次用户请求实时拉取 |
列表返回
*List模型(total+ 具体数组字段),不支持queries[]分页过滤,单次全量返回。静态数据随平台版本更新,建议客户端结合版本号做本地缓存失效。
与 Server SDK 的对应
Server SDK service.method | HTTP 方法与路径 | 返回模型 |
|---|---|---|
Locale.get | GET /v1/locale | locale |
Locale.listCodes | GET /v1/locale/codes | localeCodeList |
Locale.listContinents | GET /v1/locale/continents | continentList |
Locale.listCountries | GET /v1/locale/countries | countryList |
Locale.listCountriesEU | GET /v1/locale/countries/eu | countryList |
Locale.listCountriesPhones | GET /v1/locale/countries/phones | phoneList |
Locale.listCurrencies | GET /v1/locale/currencies | currencyList |
Locale.listLanguages | GET /v1/locale/languages | languageList |