Docs
Contents

Localization

Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1> with the intended environment API endpoint and verify that the project and credentials belong to that environment.

Overview and use cases

Locale The service provides two categories of capabilities: identification of the current requester's geographic and language environment (returns country code, continent, EU membership status, and default currency based on the client IP and the X-Appwrite-Locale header), and the platform's built-in standardized internationalization static dictionary catalog (countries and regions, EU member states, international dialing codes, continents, ISO 4217 currencies, ISO 639-1 languages, and ISO 3166-1 three-letter codes).

In multinational or multilingual enterprise intelligent applications (such as the demo project enterprise-ai-hub-210), the frontend and server can use the Locale service to uniformly render country/dialing-code dropdowns, format currency symbols, switch languages, and inject the user's region and language preferences before agent session initialization, avoiding duplicate maintenance of static dictionaries across multiple clients.

Prerequisites

Usage workflow

  1. Initialize the Client and Locale services: load the project ID and authentication credentials, and optionally call setLocale('zh-CN') to specify the display language of the returned dictionaries.

  2. Get the current caller's Locale (locale.get()): read the ip, countryCode, country, continentCode, continent, eu, and currency resolved from the caller's IP.

  3. Fetch the static dictionary catalog: call listCountries(), listCountriesEU(), listCountriesPhones(), listContinents(), listCurrencies(), listLanguages(), or listCodes() according to business form requirements, and cache by version with a TTL in the server process or frontend local storage.

Key parameters and returns

Complete Method List and Corresponding REST Endpoints

SDK Method (Node / Web / Java)Python MethodGo MethodREST EndpointReturn ModelDescription
get()get()Get()GET /v1/localeLocaleReturns the current user's geographic and currency information based on the request source IP and the X-Appwrite-Locale header.
listCodes()list_codes()ListCodes()GET /v1/locale/codesLocaleCodeListRetrieves the list of ISO 639-1 language codes (total + localeCodes[]).
listContinents()list_continents()ListContinents()GET /v1/locale/continentsContinentListRetrieves the names and two-letter codes of the world's seven continents (total + continents[]).
listCountries()list_countries()ListCountries()GET /v1/locale/countriesCountryListRetrieves the list of global country/region names and ISO 3166-1 Alpha-2 codes (total + countries[]).
listCountriesEU()list_countries_eu()ListCountriesEU()GET /v1/locale/countries/euCountryListRetrieves the list of European Union (EU) member states (total + countries[]).
listCountriesPhones()list_countries_phones()ListCountriesPhones()GET /v1/locale/countries/phonesPhoneListRetrieves the list of international dialing prefixes for each country (total + phones[]).
listCurrencies()list_currencies()ListCurrencies()GET /v1/locale/currenciesCurrencyListRetrieves the list of ISO 4217 currency symbols, names, decimal precision, and codes (total + currencies[]).
listLanguages()list_languages()ListLanguages()GET /v1/locale/languagesLanguageListRetrieves the language codes, English names, and native language names (nativeName) list (total + languages[]).

Description of Core Return Fields

ModelFieldTypeDescription
LocaleipstringThe requesting client's IP address (if behind a reverse proxy, taken from a trusted forwarding header).
LocalecountryCodestringISO 3166-1 two-letter country code (e.g., CN, US; set to -- when an internal-network IP cannot be resolved).
LocalecountrystringThe localized country name (e.g., 中国).
LocalecontinentCodestringTwo-letter continent code (e.g., AS, EU, NA).
LocalecontinentstringThe localized continent name (e.g., 亚洲).
LocaleeubooleanWhether the country is an EU member state.
LocalecurrencystringISO 4217 three-letter currency code (e.g., CNY, USD, EUR).
Country / Continentname / codestringLocalized name and two-letter standard code.
Phonecode / countryCode / countryNamestringDialing code (e.g., +86), country code (CN), and country name.
Currencysymbol / name / symbolNative / decimalDigits / rounding / code / namePluralstring / numberCurrency display symbol (¥), name, number of decimal places (e.g., 2), and three-letter code (CNY).
Languagename / code / nativeNamestringLanguage name, ISO 639-1 code (e.g., zh), and native self-designation (中文).

Errors and boundaries

SDK Category Differences

SDK categoryCoverageAuthentication methodTypical scenarios
Server SDK (Node.js / Java / Python / Go)All 8 methodsProject API Key (locale.read)Server-side dictionary preheating in multiple languages, billing currency precision validation, phone dialing-code region validation
Client / Web SDK (Web)All 8 methodsUser Session (or public access)Registration-page international dialing-code selection, frontend language switcher, client-side automatic region detection
Console SDK (Node.js / Java / Python / Go)All 8 methodsConsole Session / short-lived JWTConsole forms and region selection components

Examples by language

Available on both client and server sides; the Web tab uses the user Session and is subject to data plane permissions.

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

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT ?? '<APPBASE_ENDPOINT_WITH_V1>')
    .setProject(process.env.APPBASE_PROJECT_ID ?? '<APPBASE_PROJECT_ID>')
    .setKey(process.env.APPBASE_API_KEY!)
    .setLocale('zh-CN'); // Specify that returned country and continent names use Simplified Chinese
{
  const prepareRequest = client.prepareRequest.bind(client);
  client.prepareRequest = (...args) => {
    const request = prepareRequest(...args);
    request.options.redirect = 'error';
    return request;
  };
}

const locale = new Locale(client);

try {
    // 1. Get the current requester's region and currency information
    const current = await locale.get();
    console.log(`当前区域: ${current.country} (${current.countryCode}), 货币: ${current.currency}`);

    // 2. Get the country list, international dialing codes, and currency dictionary
    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;
}

Example Guide