Docs
文档目录

本地化

这是什么 / 何时用

Locale 服务提供两类能力:当前请求方的地理与语言环境识别(基于客户端 IP 与 X-Appwrite-Locale 请求头返回国家代码、大洲、欧盟成员状态与默认货币),以及平台内置的标准化国际化静态字典清单(国家与地区、欧盟成员国、国际电话区号、大洲、ISO 4217 货币、ISO 639-1 语言及 ISO 3166-1 三位字母代码)。

在跨国或多语种企业智能应用(如演示项目 enterprise-ai-hub-210)中,前端与服务端可通过 Locale 服务统一渲染国家/电话区号下拉框、货币符号格式化、多语言切换器,并在智能体会话初始化前注入用户所在的区域与语言偏好,避免在多端重复维护静态字典。

前置

使用骨架

  1. 初始化 Client 与 Locale 服务:装载项目 ID 与鉴权凭据,按需调用 setLocale('zh-CN') 指定返回字典的显示语种。

  2. 获取当前调用方 Locale(locale.get()):读取调用方 IP 解析出的 ip、countryCode、country、continentCode、continent、eu 与 currency。

  3. 拉取静态字典清单:按业务表单需求调用 listCountries()、listCountriesEU()、listCountriesPhones()、listContinents()、listCurrencies()、listLanguages() 或 listCodes(),并在服务端进程内或前端本地存储按版本做 TTL 缓存。

关键参数与返回

方法全集与对应 REST 端点

SDK 方法(Node / Web / Java)Python 方法Go 方法REST 端点返回模型说明
get()get()Get()GET /v1/localeLocale根据请求来源 IP 与 X-Appwrite-Locale 返回当前用户地理与货币信息。
listCodes()list_codes()ListCodes()GET /v1/locale/codesLocaleCodeList获取 ISO 639-1 语言代码清单(total + localeCodes[])。
listContinents()list_continents()ListContinents()GET /v1/locale/continentsContinentList获取全球七大洲名称与双字母代码清单(total + continents[])。
listCountries()list_countries()ListCountries()GET /v1/locale/countriesCountryList获取全球国家/地区名称与 ISO 3166-1 Alpha-2 代码清单(total + countries[])。
listCountriesEU()list_countries_eu()ListCountriesEU()GET /v1/locale/countries/euCountryList获取欧盟(EU)成员国列表(total + countries[])。
listCountriesPhones()list_countries_phones()ListCountriesPhones()GET /v1/locale/countries/phonesPhoneList获取各国国际电话拨号前缀清单(total + phones[])。
listCurrencies()list_currencies()ListCurrencies()GET /v1/locale/currenciesCurrencyList获取 ISO 4217 货币符号、名称、小数精度与代码清单(total + currencies[])。
listLanguages()list_languages()ListLanguages()GET /v1/locale/languagesLanguageList获取语言代码、英文名与本地母语名称(nativeName)清单(total + languages[])。

核心返回字段说明

模型字段类型说明
Localeipstring请求客户端 IP 地址(若经过反向代理,取受信任的转发头)。
LocalecountryCodestringISO 3166-1 两位国家代码(如 CN、US;内网 IP 解析不到时为 --)。
Localecountrystring本地化后的国家名称(如 中国)。
LocalecontinentCodestring两位大洲代码(如 AS、EU、NA)。
Localecontinentstring本地化后的大洲名称(如 亚洲)。
Localeeuboolean该国家是否属于欧盟成员国。
LocalecurrencystringISO 4217 三位货币代码(如 CNY、USD、EUR)。
Country / Continentname / codestring本地化名称与两位标准代码。
Phonecode / countryCode / countryNamestring电话区号(如 +86)、国家代码(CN)与国家名称。
Currencysymbol / name / symbolNative / decimalDigits / rounding / code / namePluralstring / number货币展示符号(¥)、名称、小数位数(如 2)与三位代码(CNY)。
Languagename / code / nativeNamestring语言名称、ISO 639-1 代码(如 zh)与母语自称(中文)。

错误与边界

SDK 类别差异

SDK 类别支持范围鉴权方式典型场景
Server SDK(Node.js / Java / Python / Go)全量 8 个方法项目 API Key(locale.read)服务端多语种字典预热、账单货币精度校验、手机区号归属校验
Client / Web SDK(Web)全量 8 个方法用户 Session(或公开访问)注册页国际区号选择、前端语言切换器、客户端区域自动识别
Console SDK(Node.js / Java / Python / Go)全量 8 个方法管理面 Session / 短期 JWT控制台表单与区域选择组件

各语言调用示例

客户端与服务端均可用;Web 页签走用户 Session,受数据面权限约束。

import { Client, Locale, AgentbaseException } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
    .setProject(process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210')
    .setKey(process.env.APPBASE_API_KEY!)
    .setLocale('zh-CN'); // 指定返回的国家与大洲名称使用简体中文

const locale = new Locale(client);

try {
    // 1. 获取当前请求方的区域与货币信息
    const current = await locale.get();
    console.log(`当前区域: ${current.country} (${current.countryCode}), 货币: ${current.currency}`);

    // 2. 获取国家列表、国际电话区号与货币字典
    const countries = await locale.listCountries();
    const phones = await locale.listCountriesPhones();
    const currencies = await locale.listCurrencies();
    const languages = await locale.listLanguages();
    console.log(`国家数: ${countries.total}, 区号数: ${phones.total}, 货币数: ${currencies.total}, 语言数: ${languages.total}`);
} catch (err) {
    if (err instanceof AgentbaseException) {
        console.error(`Locale 调用失败 [${err.code} ${err.type}]: ${err.message}`);
    }
    throw err;
}

示例指引