本地化 API
本地化静态数据:当前用户 Locale,国家、大洲、货币、语言、时区等清单。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1。 - 路径前缀
/locale;无状态端点,返回静态数据。
认证与权限
认证与请求头约定见 通用约定。
- spec 认证标注为
Project + Session(客户端面工具),scopelocale.read;经 Server SDK 以项目头调用。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
GET /locale | 当前用户 locale |
GET /locale/codes / continents / countries / countries/eu / countries/phones / currencies / languages | 本地化静态清单 |
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。
Locale
GET /v1/locale
按请求 IP 解析当前用户地理与本地化信息:国家、大洲、EU 归属与建议货币;配合 locale 请求头可返回对应语言名称。
输入:无 path/query/body 参数。
输出:返回 locale:
| 字段 | 类型 | 说明 |
|---|---|---|
ip | string | 用户 IP 地址 |
countryCode | string | ISO 3166-1 两位国家代码 |
country | string | 国家名(支持本地化) |
continentCode | string | 大洲代码:AF / AN / AS / EU / NA / OC / SA |
continent | string | 大洲名(支持本地化) |
eu | boolean | 是否属于欧盟 |
currency | string | ISO 4217 三位货币代码 |
调用示例:
curl "https://<your-endpoint>/v1/locale" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"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),供前端语言下拉使用。
输入:无 path/query/body 参数。
输出:返回 localeCodeList(total + localeCodes[],元素含 code、name)。
调用示例:
curl "https://<your-endpoint>/v1/locale/codes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_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://<your-endpoint>/v1/locale/continents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_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://<your-endpoint>/v1/locale/countries" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_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://<your-endpoint>/v1/locale/countries/eu" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"countries": [
{
"name": "Germany",
"code": "DE"
},
{
"name": "France",
"code": "FR"
}
]
}GET /v1/locale/countries/phones
列出各国电话区号:与国家代码对照,用于手机号输入组件。
输入:无 path/query/body 参数。
输出:返回 phoneList(total + phones[],元素含 code(如 +1)、countryCode、countryName)。
调用示例:
curl "https://<your-endpoint>/v1/locale/countries/phones" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_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[],元素字段:symbol、name、symbolNative、decimalDigits、rounding、code、namePlural)。
调用示例:
curl "https://<your-endpoint>/v1/locale/currencies" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_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://<your-endpoint>/v1/locale/languages" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"languages": [
{
"name": "Italian",
"code": "it",
"nativeName": "Italiano"
},
{
"name": "Chinese",
"code": "zh",
"nativeName": "中文"
}
]
}错误与边界
- 列表返回
List模型(total+entries);静态数据随实例版本更新,不做客户端缓存假设。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Locale.get / listCodes / listContinents / listCountries / listCountriesEU / listCountriesPhones / listCurrencies / listLanguages | /locale* |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0 同名 service。 - 语义深度参考:
skills/ob-agentbase/references/environment-context.md。