AgentbaseDocs
文档目录

本地化 API

提供面向全球化业务与企业多语言工作台的本地化静态字典与地理位置解析服务:支持基于客户端请求 IP 解析国家、大洲、欧盟归属与建议货币,并提供 ISO 标准国家、大洲、电话区号、货币与语言字典清单。

服务与资源边界

Locale API 是 Agentbase 平台内置的无状态国际化(i18n)与区域元数据基础服务,服务边界与核心特性如下:

资源与基础路径

模型名称关联端点核心字段说明
localeGET /localeip, countryCode, country, continentCode, continent, eu, currency当前请求方的地理位置与区域本地化画像
localeCodeListGET /locale/codestotal, localeCodes[] (code, name)平台支持的 ISO 639-1 / BCP-47 语言区域代码列表
continentListGET /locale/continentstotal, continents[] (name, code)七大洲代码与本地化名称列表
countryListGET /locale/countries (/eu)total, countries[] (name, code)全球国家/地区或欧盟成员国列表
phoneListGET /locale/countries/phonestotal, phones[] (code, countryCode, countryName)国际长途电话区号映射列表
currencyListGET /locale/currenciestotal, currencies[] (symbol, name, code, decimalDigits, rounding)ISO 4217 货币符号与精度规则列表
languageListGET /locale/languagestotal, 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指定返回国家、大洲名称的本地化语言代码

端点总览

Locale 服务共包含 8 个只读端点,分为「请求方区域探测」与「标准枚举字典」两大类:

分类端点返回模型典型场景
请求方区域探测GET /v1/localelocale智能客服会话初始化时自动识别访客所在时区/国家与默认语言
语言与区域代码GET /v1/locale/codes、GET /v1/locale/languageslocaleCodeList、languageList控制台或客户端个人中心的语言切换下拉菜单
地理与电话区号GET /v1/locale/continents、GET /v1/locale/countries、GET /v1/locale/countries/eu、GET /v1/locale/countries/phonescontinentList、countryList、phoneList手机号短信验证码登录组件(如 +86)、GDPR 欧盟合规分流判定
货币与结算规则GET /v1/locale/currenciescurrencyListAI 网关计费账单展示、多币种小数位与四舍五入格式化

端点清单

方法 + 路径Scope幂等性用途
GET /localelocale.read是获取当前请求方的地理与本地化信息
GET /locale/codeslocale.read是列出全部支持的 Locale 语言区域代码
GET /locale/continentslocale.read是列出全部大洲代码与名称
GET /locale/countrieslocale.read是列出全部国家/地区代码与名称
GET /locale/countries/eulocale.read是列出当前欧盟(EU)成员国
GET /locale/countries/phoneslocale.read是列出各国电话区号与国家对照表
GET /locale/currencieslocale.read是列出全部 ISO 4217 货币及格式规则
GET /locale/languageslocale.read是列出全部 ISO 639-1 语言及母语名称

端点详解

多语言字典切换与缓存实践

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。

Locale

GET /v1/locale

按请求 IP 解析当前用户地理与本地化信息:国家、大洲、EU 归属与建议货币;配合 X-Appwrite-Locale 请求头可返回对应语言名称。

输入:无 path/query/body 参数(可选请求头 X-Appwrite-Locale)。

输出:返回 200 OK + locale 模型:

字段类型说明
ipstring客户端 IP 地址
countryCodestringISO 3166-1 两位国家代码(如 CN、US);内网未知 IP 时为 ""
countrystring国家名称(支持 X-Appwrite-Locale 本地化)
continentCodestring大洲代码:AF / AN / AS / EU / NA / OC / SA
continentstring大洲名称(支持本地化)
euboolean是否属于欧盟(EU)成员国
currencystringISO 4217 三位货币代码(如 CNY、USD)

调用示例:

curl "https://appbuild-sit.oceanbase.com/v1/locale" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -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)。

调用示例:

curl "https://appbuild-sit.oceanbase.com/v1/locale/codes" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

响应示例:

{
  "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)。

调用示例:

curl "https://appbuild-sit.oceanbase.com/v1/locale/continents" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

响应示例:

{
  "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)。

调用示例:

curl "https://appbuild-sit.oceanbase.com/v1/locale/countries" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

响应示例:

{
  "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)。

调用示例:

curl "https://appbuild-sit.oceanbase.com/v1/locale/countries/eu" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

响应示例:

{
  "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)。

调用示例:

curl "https://appbuild-sit.oceanbase.com/v1/locale/countries/phones" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

响应示例:

{
  "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[]):

字段类型说明
symbolstring国际通用货币符号(如 $、¥)
namestring货币单数名称(如 Chinese yuan)
symbolNativestring本地货币符号
decimalDigitsinteger标准小数位数(如 CNY 为 2,JPY 为 0)
roundingnumber最小舍入步长(通常为 0)
codestringISO 4217 三位大写代码(如 CNY、USD)
namePluralstring货币复数名称

调用示例:

curl "https://appbuild-sit.oceanbase.com/v1/locale/currencies" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

响应示例:

{
  "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)。

调用示例:

curl "https://appbuild-sit.oceanbase.com/v1/locale/languages" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

响应示例:

{
  "total": 2,
  "languages": [
    {
      "name": "Italian",
      "code": "it",
      "nativeName": "Italiano"
    },
    {
      "name": "Chinese",
      "code": "zh",
      "nativeName": "中文"
    }
  ]
}

错误与边界

HTTP 状态码错误类型 (type)触发原因排障建议
401 Unauthorizedgeneral_access_forbidden缺少 X-Appwrite-Project 或项目 ID 不存在检查请求头中的项目 ID(如 enterprise-ai-hub-210)
401 Unauthorizedgeneral_unauthorized_scopeAPI Key 未授予 locale.read 权限在控制台 API Key 设置中勾选 locale.read
429 Too Many Requestsgeneral_rate_limit_exceeded高频轮询静态字典触发实例限流字典列表(countries/currencies/phones/languages)应缓存在应用内存中,避免按每次用户请求实时拉取

与 Server SDK 的对应

Server SDK service.methodHTTP 方法与路径返回模型
Locale.getGET /v1/localelocale
Locale.listCodesGET /v1/locale/codeslocaleCodeList
Locale.listContinentsGET /v1/locale/continentscontinentList
Locale.listCountriesGET /v1/locale/countriescountryList
Locale.listCountriesEUGET /v1/locale/countries/eucountryList
Locale.listCountriesPhonesGET /v1/locale/countries/phonesphoneList
Locale.listCurrenciesGET /v1/locale/currenciescurrencyList
Locale.listLanguagesGET /v1/locale/languageslanguageList

事实源