From f14da50e5d8aad6934ab659cef43a98f53046495 Mon Sep 17 00:00:00 2001 From: eldadfux Date: Tue, 18 Nov 2025 20:55:23 +0100 Subject: [PATCH] Locale WIP --- src/routes/docs/Sidebar.svelte | 13 + .../docs/products/locale/+layout.svelte | 70 +++++ src/routes/docs/products/locale/+page.markdoc | 49 ++++ .../products/locale/continents/+page.markdoc | 170 +++++++++++ .../products/locale/countries/+page.markdoc | 202 +++++++++++++ .../products/locale/currencies/+page.markdoc | 240 +++++++++++++++ .../products/locale/languages/+page.markdoc | 276 ++++++++++++++++++ .../products/locale/phone-codes/+page.markdoc | 256 ++++++++++++++++ .../products/locale/quick-start/+page.markdoc | 182 ++++++++++++ .../products/locale/user-locale/+page.markdoc | 161 ++++++++++ 10 files changed, 1619 insertions(+) create mode 100644 src/routes/docs/products/locale/+layout.svelte create mode 100644 src/routes/docs/products/locale/+page.markdoc create mode 100644 src/routes/docs/products/locale/continents/+page.markdoc create mode 100644 src/routes/docs/products/locale/countries/+page.markdoc create mode 100644 src/routes/docs/products/locale/currencies/+page.markdoc create mode 100644 src/routes/docs/products/locale/languages/+page.markdoc create mode 100644 src/routes/docs/products/locale/phone-codes/+page.markdoc create mode 100644 src/routes/docs/products/locale/quick-start/+page.markdoc create mode 100644 src/routes/docs/products/locale/user-locale/+page.markdoc diff --git a/src/routes/docs/Sidebar.svelte b/src/routes/docs/Sidebar.svelte index fbee7c5cad..e671314edd 100644 --- a/src/routes/docs/Sidebar.svelte +++ b/src/routes/docs/Sidebar.svelte @@ -25,6 +25,12 @@ href: '/docs/sdks', icon: 'icon-cog' }, + { + label: 'Blog', + href: '/blog', + icon: 'icon-document-text', + openInNewTab: true + }, { label: 'Changelog', href: '/changelog', @@ -98,6 +104,13 @@ icon: 'icon-user-circle', isParent: true, new: isNewUntil('1 Jan 2026') + }, + { + label: 'Locale', + href: '/docs/products/locale', + icon: 'icon-location-marker', + isParent: true, + new: isNewUntil('1 Jan 2026') } ] }, diff --git a/src/routes/docs/products/locale/+layout.svelte b/src/routes/docs/products/locale/+layout.svelte new file mode 100644 index 0000000000..b2269f2a8b --- /dev/null +++ b/src/routes/docs/products/locale/+layout.svelte @@ -0,0 +1,70 @@ + + + + + + + + diff --git a/src/routes/docs/products/locale/+page.markdoc b/src/routes/docs/products/locale/+page.markdoc new file mode 100644 index 0000000000..1ae6ec1aaa --- /dev/null +++ b/src/routes/docs/products/locale/+page.markdoc @@ -0,0 +1,49 @@ +--- +layout: article +title: Locale +description: Customize your app based on user location. Get user location, countries, continents, currencies, phone codes, and more with Appwrite Locale. +back: /docs +--- + +Appwrite **Locale** provides comprehensive location and localization data to help you customize your application based on your users' location. The Locale service allows you to get user location information, IP addresses, country and continent names, phone codes, currencies, and language data. + +All Locale endpoints support multiple locales, allowing you to fetch information in your app's language. Country codes follow the [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) standard, ensuring consistency and compatibility with international standards. + +{% arrow_link href="/docs/products/locale/quick-start" %} +Get started with Locale in minutes +{% /arrow_link %} + +# Capabilities {% #capabilities %} + +Appwrite Locale supports multiple features to help you build location-aware and localized applications. + +{% cards %} +{% cards_item href="/docs/products/locale/user-locale" title="User locale" %} +Get the current user's location based on IP address, including country, continent, and currency information. +{% /cards_item %} +{% cards_item href="/docs/products/locale/countries" title="Countries" %} +Retrieve comprehensive country data including names, codes, and EU membership status. +{% /cards_item %} +{% cards_item href="/docs/products/locale/continents" title="Continents" %} +Access continent information with names and codes for geographic organization. +{% /cards_item %} +{% cards_item href="/docs/products/locale/currencies" title="Currencies" %} +Get currency data including symbols, names, plural forms, and decimal precision. +{% /cards_item %} +{% cards_item href="/docs/products/locale/phone-codes" title="Phone codes" %} +Retrieve international phone codes for all countries to build phone number inputs. +{% /cards_item %} +{% cards_item href="/docs/products/locale/languages" title="Languages" %} +Access language data classified by ISO 639-1 with codes and native names. +{% /cards_item %} +{% /cards %} + +# Multi-locale support {% #multi-locale %} + +The Locale service supports multiple locales, allowing you to fetch country and continent information in your app's language. To switch locales, pass the `X-Appwrite-Locale` header or use the `setLocale` method in any of our available SDKs. [View the list of available locales](https://github.com/appwrite/appwrite/blob/master/app/config/locale/codes.php). + +# No authentication required {% #no-authentication %} + +The Locale service is publicly accessible and does not require user authentication or API keys. All endpoints can be called directly from client applications, making it easy to integrate location and localization data into any part of your application. + + diff --git a/src/routes/docs/products/locale/continents/+page.markdoc b/src/routes/docs/products/locale/continents/+page.markdoc new file mode 100644 index 0000000000..16c246d251 --- /dev/null +++ b/src/routes/docs/products/locale/continents/+page.markdoc @@ -0,0 +1,170 @@ +--- +layout: article +title: Continents +description: Access continent information with names and codes for geographic organization and regional features. +--- + +The continents endpoint provides access to continent information for geographic organization. This is useful for grouping countries by region, building regional features, and organizing location-based data. + +# List continents {% #list-continents %} + +Retrieve a list of all continents with their names and codes. + +{% multicode %} +```client-web +import { Client, Locale } from "appwrite"; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const continents = await locale.listContinents(); + +console.log(continents); +// { +// total: 7, +// continents: [ +// { name: 'Africa', code: 'AF' }, +// { name: 'Antarctica', code: 'AN' }, +// { name: 'Asia', code: 'AS' }, +// { name: 'Europe', code: 'EU' }, +// { name: 'North America', code: 'NA' }, +// { name: 'Oceania', code: 'OC' }, +// { name: 'South America', code: 'SA' } +// ] +// } +``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +final client = Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +final locale = Locale(client); + +Future result = locale.listContinents().then((response) { + print(response.total); + response.continents.forEach((continent) { + print('${continent.name} (${continent.code})'); + }); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +let locale = Locale(client) + +let continents = try await locale.listContinents() + +print(continents.total) +for continent in continents.continents { + print("\(continent.name) (\(continent.code))") +} +``` +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Locale + +val client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +val locale = Locale(client) + +val continents = locale.listContinents() + +println(continents.total) +continents.continents.forEach { continent -> + println("${continent.name} (${continent.code})") +} +``` +```client-react-native +import { Client, Locale } from 'react-native-appwrite'; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const continents = await locale.listContinents(); + +console.log(continents); +``` +{% /multicode %} + +# Response structure {% #response-structure %} + +The `listContinents` method returns a continents list with the following structure: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| total | integer | Total number of continents (typically 7) | +| continents | array | Array of continent objects, each containing `name` and `code` | + +# Continent codes {% #continent-codes %} + +Continent codes use standard two-letter abbreviations: +- `AF` - Africa +- `AN` - Antarctica +- `AS` - Asia +- `EU` - Europe +- `NA` - North America +- `OC` - Oceania +- `SA` - South America + +# Use cases {% #use-cases %} + +Continent lists are commonly used for: + +- **Regional organization**: Group countries by continent for navigation and filtering +- **Geographic analytics**: Analyze user distribution and engagement by continent +- **Regional features**: Enable continent-specific features or content +- **Data visualization**: Create maps and charts organized by continent +- **Content delivery**: Optimize content delivery based on regional preferences + +# Multi-locale support {% #multi-locale %} + +Continent names can be retrieved in different languages by setting the locale: + +{% multicode %} +```client-web +// Set locale to French +client.setLocale('fr'); + +const continents = await locale.listContinents(); +// Continent names will be in French +``` +```client-flutter +client.setLocale('fr'); + +final continents = await locale.listContinents(); +``` +```client-apple +client.setLocale("fr") + +let continents = try await locale.listContinents() +``` +```client-android-kotlin +client.setLocale("fr") + +val continents = locale.listContinents() +``` +```client-react-native +client.setLocale('fr'); + +const continents = await locale.listContinents(); +``` +{% /multicode %} + + diff --git a/src/routes/docs/products/locale/countries/+page.markdoc b/src/routes/docs/products/locale/countries/+page.markdoc new file mode 100644 index 0000000000..72da04d958 --- /dev/null +++ b/src/routes/docs/products/locale/countries/+page.markdoc @@ -0,0 +1,202 @@ +--- +layout: article +title: Countries +description: Retrieve comprehensive country data including names, codes, and EU membership status for building location-aware applications. +--- + +The countries endpoint provides access to comprehensive country information for all countries worldwide. This is useful for building country selectors, location-based features, and internationalization functionality. + +# List countries {% #list-countries %} + +Retrieve a list of all countries with their names and codes. Country codes follow the [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) alpha-2 standard. + +{% multicode %} +```client-web +import { Client, Locale } from "appwrite"; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const countries = await locale.listCountries(); + +console.log(countries); +// { +// total: 195, +// countries: [ +// { name: 'United States', code: 'US' }, +// { name: 'United Kingdom', code: 'GB' }, +// ... +// ] +// } +``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +final client = Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +final locale = Locale(client); + +Future result = locale.listCountries().then((response) { + print(response.total); + response.countries.forEach((country) { + print('${country.name} (${country.code})'); + }); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +let locale = Locale(client) + +let countries = try await locale.listCountries() + +print(countries.total) +for country in countries.countries { + print("\(country.name) (\(country.code))") +} +``` +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Locale + +val client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +val locale = Locale(client) + +val countries = locale.listCountries() + +println(countries.total) +countries.countries.forEach { country -> + println("${country.name} (${country.code})") +} +``` +```client-react-native +import { Client, Locale } from 'react-native-appwrite'; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const countries = await locale.listCountries(); + +console.log(countries); +``` +{% /multicode %} + +# Response structure {% #response-structure %} + +The `listCountries` method returns a countries list with the following structure: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| total | integer | Total number of countries | +| countries | array | Array of country objects, each containing `name` and `code` | + +# Country codes {% #country-codes %} + +Country codes follow the ISO 3166-1 alpha-2 standard, which uses two-letter codes to uniquely identify countries. These codes are widely used in international standards and are compatible with other Appwrite services. + +# Use cases {% #use-cases %} + +Country lists are commonly used for: + +- **Country selectors**: Build dropdown menus or searchable lists for user registration and profile forms +- **Address forms**: Pre-populate country fields in shipping and billing address forms +- **Regional features**: Enable or disable features based on available countries +- **Analytics**: Track user distribution and engagement by country +- **Compliance**: Apply country-specific regulations, tax rules, or content restrictions + +# List EU countries {% #list-eu-countries %} + +You can also retrieve a list of countries that are currently members of the European Union: + +{% multicode %} +```client-web +const euCountries = await locale.listCountriesEU(); + +console.log(euCountries); +// { +// total: 27, +// countries: [ +// { name: 'Germany', code: 'DE' }, +// { name: 'France', code: 'FR' }, +// ... +// ] +// } +``` +```client-flutter +Future result = locale.listCountriesEU().then((response) { + print(response.total); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +let euCountries = try await locale.listCountriesEU() + +print(euCountries.total) +``` +```client-android-kotlin +val euCountries = locale.listCountriesEU() + +println(euCountries.total) +``` +```client-react-native +const euCountries = await locale.listCountriesEU(); + +console.log(euCountries); +``` +{% /multicode %} + +# Multi-locale support {% #multi-locale %} + +Country names can be retrieved in different languages by setting the locale: + +{% multicode %} +```client-web +// Set locale to French +client.setLocale('fr'); + +const countries = await locale.listCountries(); +// Country names will be in French +``` +```client-flutter +client.setLocale('fr'); + +final countries = await locale.listCountries(); +``` +```client-apple +client.setLocale("fr") + +let countries = try await locale.listCountries() +``` +```client-android-kotlin +client.setLocale("fr") + +val countries = locale.listCountries() +``` +```client-react-native +client.setLocale('fr'); + +const countries = await locale.listCountries(); +``` +{% /multicode %} + + diff --git a/src/routes/docs/products/locale/currencies/+page.markdoc b/src/routes/docs/products/locale/currencies/+page.markdoc new file mode 100644 index 0000000000..f43f391793 --- /dev/null +++ b/src/routes/docs/products/locale/currencies/+page.markdoc @@ -0,0 +1,240 @@ +--- +layout: article +title: Currencies +description: Get currency data including symbols, names, plural forms, and decimal precision for building payment and pricing features. +--- + +The currencies endpoint provides comprehensive currency information for all major and minor currencies worldwide. This is essential for building payment systems, pricing displays, and financial applications. + +# List currencies {% #list-currencies %} + +Retrieve a list of all currencies with their symbols, names, plural forms, and decimal precision. + +{% multicode %} +```client-web +import { Client, Locale } from "appwrite"; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const currencies = await locale.listCurrencies(); + +console.log(currencies); +// { +// total: 150+, +// currencies: [ +// { +// symbol: '$', +// name: 'US Dollar', +// symbolNative: '$', +// decimalDigits: 2, +// rounding: 0, +// code: 'USD', +// namePlural: 'US dollars' +// }, +// ... +// ] +// } +``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +final client = Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +final locale = Locale(client); + +Future result = locale.listCurrencies().then((response) { + print(response.total); + response.currencies.forEach((currency) { + print('${currency.name} (${currency.code}) - ${currency.symbol}'); + }); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +let locale = Locale(client) + +let currencies = try await locale.listCurrencies() + +print(currencies.total) +for currency in currencies.currencies { + print("\(currency.name) (\(currency.code)) - \(currency.symbol)") +} +``` +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Locale + +val client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +val locale = Locale(client) + +val currencies = locale.listCurrencies() + +println(currencies.total) +currencies.currencies.forEach { currency -> + println("${currency.name} (${currency.code}) - ${currency.symbol}") +} +``` +```client-react-native +import { Client, Locale } from 'react-native-appwrite'; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const currencies = await locale.listCurrencies(); + +console.log(currencies); +``` +{% /multicode %} + +# Response structure {% #response-structure %} + +The `listCurrencies` method returns a currencies list with the following structure: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| total | integer | Total number of currencies | +| currencies | array | Array of currency objects | + +Each currency object contains: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| symbol | string | Currency symbol (e.g., `$`, `€`) | +| name | string | Currency name (e.g., "US Dollar") | +| symbolNative | string | Native currency symbol | +| decimalDigits | integer | Number of decimal digits (typically 0 or 2) | +| rounding | number | Rounding factor | +| code | string | ISO 4217 currency code (e.g., `USD`, `EUR`) | +| namePlural | string | Plural form of currency name | + +# Currency codes {% #currency-codes %} + +Currency codes follow the ISO 4217 standard, which uses three-letter codes to uniquely identify currencies. These codes are widely used in financial systems and payment processing. + +# Use cases {% #use-cases %} + +Currency lists are commonly used for: + +- **Payment processing**: Display and process payments in multiple currencies +- **Pricing displays**: Show prices in user's local currency with proper formatting +- **Currency conversion**: Build currency conversion features and calculators +- **E-commerce**: Support multi-currency product catalogs and checkout flows +- **Financial applications**: Build budgeting, accounting, and financial tracking apps + +# Formatting currencies {% #formatting-currencies %} + +Use the currency data to format prices correctly: + +{% multicode %} +```client-web +const currencies = await locale.listCurrencies(); +const usd = currencies.currencies.find(c => c.code === 'USD'); + +function formatPrice(amount, currency) { + return `${currency.symbol}${amount.toFixed(currency.decimalDigits)}`; +} + +const price = formatPrice(99.99, usd); +console.log(price); // "$99.99" +``` +```client-flutter +final currencies = await locale.listCurrencies(); +final usd = currencies.currencies.firstWhere((c) => c.code == 'USD'); + +String formatPrice(double amount, currency) { + return '${currency.symbol}${amount.toStringAsFixed(currency.decimalDigits)}'; +} + +final price = formatPrice(99.99, usd); +print(price); // "$99.99" +``` +```client-apple +let currencies = try await locale.listCurrencies() +let usd = currencies.currencies.first { $0.code == "USD" } + +func formatPrice(amount: Double, currency: Currency) -> String { + return "\(currency.symbol)\(String(format: "%.\(currency.decimalDigits)f", amount))" +} + +let price = formatPrice(amount: 99.99, currency: usd!) +print(price) // "$99.99" +``` +```client-android-kotlin +val currencies = locale.listCurrencies() +val usd = currencies.currencies.find { it.code == "USD" } + +fun formatPrice(amount: Double, currency: Currency): String { + return "${currency.symbol}${String.format("%.${currency.decimalDigits}f", amount)}" +} + +val price = formatPrice(99.99, usd!!) +println(price) // "$99.99" +``` +```client-react-native +const currencies = await locale.listCurrencies(); +const usd = currencies.currencies.find(c => c.code === 'USD'); + +function formatPrice(amount, currency) { + return `${currency.symbol}${amount.toFixed(currency.decimalDigits)}`; +} + +const price = formatPrice(99.99, usd); +console.log(price); // "$99.99" +``` +{% /multicode %} + +# Multi-locale support {% #multi-locale %} + +Currency names can be retrieved in different languages by setting the locale: + +{% multicode %} +```client-web +// Set locale to French +client.setLocale('fr'); + +const currencies = await locale.listCurrencies(); +// Currency names will be in French +``` +```client-flutter +client.setLocale('fr'); + +final currencies = await locale.listCurrencies(); +``` +```client-apple +client.setLocale("fr") + +let currencies = try await locale.listCurrencies() +``` +```client-android-kotlin +client.setLocale("fr") + +val currencies = locale.listCurrencies() +``` +```client-react-native +client.setLocale('fr'); + +const currencies = await locale.listCurrencies(); +``` +{% /multicode %} + + diff --git a/src/routes/docs/products/locale/languages/+page.markdoc b/src/routes/docs/products/locale/languages/+page.markdoc new file mode 100644 index 0000000000..ce1f3af75e --- /dev/null +++ b/src/routes/docs/products/locale/languages/+page.markdoc @@ -0,0 +1,276 @@ +--- +layout: article +title: Languages +description: Access language data classified by ISO 639-1 with codes and native names for building multilingual applications. +--- + +The languages endpoint provides access to language information classified by ISO 639-1 standard. This is useful for building language selectors, implementing multilingual features, and displaying language options to users. + +# List languages {% #list-languages %} + +Retrieve a list of all languages with their codes, English names, and native names. + +{% multicode %} +```client-web +import { Client, Locale } from "appwrite"; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const languages = await locale.listLanguages(); + +console.log(languages); +// { +// total: 100+, +// languages: [ +// { +// name: 'English', +// code: 'en', +// nativeName: 'English' +// }, +// { +// name: 'Spanish', +// code: 'es', +// nativeName: 'Español' +// }, +// ... +// ] +// } +``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +final client = Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +final locale = Locale(client); + +Future result = locale.listLanguages().then((response) { + print(response.total); + response.languages.forEach((language) { + print('${language.name} (${language.code}) - ${language.nativeName}'); + }); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +let locale = Locale(client) + +let languages = try await locale.listLanguages() + +print(languages.total) +for language in languages.languages { + print("\(language.name) (\(language.code)) - \(language.nativeName)") +} +``` +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Locale + +val client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +val locale = Locale(client) + +val languages = locale.listLanguages() + +println(languages.total) +languages.languages.forEach { language -> + println("${language.name} (${language.code}) - ${language.nativeName}") +} +``` +```client-react-native +import { Client, Locale } from 'react-native-appwrite'; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const languages = await locale.listLanguages(); + +console.log(languages); +``` +{% /multicode %} + +# Response structure {% #response-structure %} + +The `listLanguages` method returns a languages list with the following structure: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| total | integer | Total number of languages | +| languages | array | Array of language objects | + +Each language object contains: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| name | string | Language name in English | +| code | string | Two-letter language code (ISO 639-1) | +| nativeName | string | Language name in its native script | + +# Language codes {% #language-codes %} + +Language codes follow the ISO 639-1 standard, which uses two-letter codes to uniquely identify languages. These codes are widely used in internationalization and localization systems. + +# Use cases {% #use-cases %} + +Language lists are commonly used for: + +- **Language selectors**: Build dropdown menus or lists for users to choose their preferred language +- **Multilingual apps**: Implement language switching and localization features +- **Content localization**: Display content in user's preferred language +- **User preferences**: Store and apply user language preferences across the application +- **Internationalization**: Support multiple languages in your application interface + +# Building language selectors {% #building-language-selectors %} + +Use language data to build language selection components: + +{% multicode %} +```client-web +const languages = await locale.listLanguages(); + +// Build language selector +const languageOptions = languages.languages.map(lang => ({ + label: `${lang.nativeName} (${lang.name})`, + value: lang.code, + code: lang.code +})); + +// Set app language +function setAppLanguage(code) { + client.setLocale(code); + // Reload or update app content +} +``` +```client-flutter +final languages = await locale.listLanguages(); + +// Build language selector +final languageOptions = languages.languages.map((lang) { + return { + 'label': '${lang.nativeName} (${lang.name})', + 'value': lang.code, + 'code': lang.code + }; +}).toList(); + +// Set app language +void setAppLanguage(String code) { + client.setLocale(code); + // Reload or update app content +} +``` +```client-apple +let languages = try await locale.listLanguages() + +// Build language selector +let languageOptions = languages.languages.map { lang in + [ + "label": "\(lang.nativeName) (\(lang.name))", + "value": lang.code, + "code": lang.code + ] +} + +// Set app language +func setAppLanguage(code: String) { + client.setLocale(code) + // Reload or update app content +} +``` +```client-android-kotlin +val languages = locale.listLanguages() + +// Build language selector +val languageOptions = languages.languages.map { lang -> + mapOf( + "label" to "${lang.nativeName} (${lang.name})", + "value" to lang.code, + "code" to lang.code + ) +} + +// Set app language +fun setAppLanguage(code: String) { + client.setLocale(code) + // Reload or update app content +} +``` +```client-react-native +const languages = await locale.listLanguages(); + +// Build language selector +const languageOptions = languages.languages.map(lang => ({ + label: `${lang.nativeName} (${lang.name})`, + value: lang.code, + code: lang.code +})); + +// Set app language +function setAppLanguage(code) { + client.setLocale(code); + // Reload or update app content +} +``` +{% /multicode %} + +# List locale codes {% #list-locale-codes %} + +You can also retrieve a list of all available locale codes: + +{% multicode %} +```client-web +const localeCodes = await locale.listCodes(); + +console.log(localeCodes); +// { +// total: 100+, +// codes: ['en', 'es', 'fr', 'de', ...] +// } +``` +```client-flutter +Future result = locale.listCodes().then((response) { + print(response.total); + print(response.codes); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +let localeCodes = try await locale.listCodes() + +print(localeCodes.total) +print(localeCodes.codes) +``` +```client-android-kotlin +val localeCodes = locale.listCodes() + +println(localeCodes.total) +println(localeCodes.codes) +``` +```client-react-native +const localeCodes = await locale.listCodes(); + +console.log(localeCodes); +``` +{% /multicode %} + + diff --git a/src/routes/docs/products/locale/phone-codes/+page.markdoc b/src/routes/docs/products/locale/phone-codes/+page.markdoc new file mode 100644 index 0000000000..1d4c8e553c --- /dev/null +++ b/src/routes/docs/products/locale/phone-codes/+page.markdoc @@ -0,0 +1,256 @@ +--- +layout: article +title: Phone codes +description: Retrieve international phone codes for all countries to build phone number inputs and validation. +--- + +The phone codes endpoint provides access to international dialing codes for all countries. This is essential for building phone number input fields, validation, and formatting features. + +# List phone codes {% #list-phone-codes %} + +Retrieve a list of all countries with their international phone codes. + +{% multicode %} +```client-web +import { Client, Locale } from "appwrite"; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const phones = await locale.listCountriesPhones(); + +console.log(phones); +// { +// total: 195, +// phones: [ +// { code: '+1', countryCode: 'US', countryName: 'United States' }, +// { code: '+44', countryCode: 'GB', countryName: 'United Kingdom' }, +// ... +// ] +// } +``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +final client = Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +final locale = Locale(client); + +Future result = locale.listCountriesPhones().then((response) { + print(response.total); + response.phones.forEach((phone) { + print('${phone.countryName} (${phone.countryCode}): ${phone.code}'); + }); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +let locale = Locale(client) + +let phones = try await locale.listCountriesPhones() + +print(phones.total) +for phone in phones.phones { + print("\(phone.countryName) (\(phone.countryCode)): \(phone.code)") +} +``` +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Locale + +val client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +val locale = Locale(client) + +val phones = locale.listCountriesPhones() + +println(phones.total) +phones.phones.forEach { phone -> + println("${phone.countryName} (${phone.countryCode}): ${phone.code}") +} +``` +```client-react-native +import { Client, Locale } from 'react-native-appwrite'; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const phones = await locale.listCountriesPhones(); + +console.log(phones); +``` +{% /multicode %} + +# Response structure {% #response-structure %} + +The `listCountriesPhones` method returns a phones list with the following structure: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| total | integer | Total number of countries with phone codes | +| phones | array | Array of phone code objects | + +Each phone code object contains: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| code | string | International dialing code (e.g., `+1`, `+44`) | +| countryCode | string | Two-letter country code (ISO 3166-1 alpha-2) | +| countryName | string | Country name | + +# Use cases {% #use-cases %} + +Phone codes are commonly used for: + +- **Phone number inputs**: Build country code selectors for phone number input fields +- **Phone validation**: Validate phone numbers based on country code format +- **Phone formatting**: Format phone numbers with proper country codes +- **User registration**: Collect phone numbers with country code selection +- **SMS verification**: Send SMS messages to users with proper country codes + +# Building phone inputs {% #building-phone-inputs %} + +Use phone codes to build phone number input components: + +{% multicode %} +```client-web +const phones = await locale.listCountriesPhones(); + +// Build country code selector +const countrySelect = phones.phones.map(phone => ({ + label: `${phone.countryName} ${phone.code}`, + value: phone.code, + countryCode: phone.countryCode +})); + +// Format phone number with country code +function formatPhoneNumber(countryCode, number) { + const phone = phones.phones.find(p => p.countryCode === countryCode); + return `${phone.code} ${number}`; +} +``` +```client-flutter +final phones = await locale.listCountriesPhones(); + +// Build country code selector +final countryOptions = phones.phones.map((phone) => { + return { + 'label': '${phone.countryName} ${phone.code}', + 'value': phone.code, + 'countryCode': phone.countryCode + }; +}).toList(); + +// Format phone number with country code +String formatPhoneNumber(String countryCode, String number) { + final phone = phones.phones.firstWhere((p) => p.countryCode == countryCode); + return '${phone.code} $number'; +} +``` +```client-apple +let phones = try await locale.listCountriesPhones() + +// Build country code selector +let countryOptions = phones.phones.map { phone in + [ + "label": "\(phone.countryName) \(phone.code)", + "value": phone.code, + "countryCode": phone.countryCode + ] +} + +// Format phone number with country code +func formatPhoneNumber(countryCode: String, number: String) -> String { + let phone = phones.phones.first { $0.countryCode == countryCode }! + return "\(phone.code) \(number)" +} +``` +```client-android-kotlin +val phones = locale.listCountriesPhones() + +// Build country code selector +val countryOptions = phones.phones.map { phone -> + mapOf( + "label" to "${phone.countryName} ${phone.code}", + "value" to phone.code, + "countryCode" to phone.countryCode + ) +} + +// Format phone number with country code +fun formatPhoneNumber(countryCode: String, number: String): String { + val phone = phones.phones.find { it.countryCode == countryCode }!! + return "${phone.code} $number" +} +``` +```client-react-native +const phones = await locale.listCountriesPhones(); + +// Build country code selector +const countryOptions = phones.phones.map(phone => ({ + label: `${phone.countryName} ${phone.code}`, + value: phone.code, + countryCode: phone.countryCode +})); + +// Format phone number with country code +function formatPhoneNumber(countryCode, number) { + const phone = phones.phones.find(p => p.countryCode === countryCode); + return `${phone.code} ${number}`; +} +``` +{% /multicode %} + +# Multi-locale support {% #multi-locale %} + +Country names can be retrieved in different languages by setting the locale: + +{% multicode %} +```client-web +// Set locale to French +client.setLocale('fr'); + +const phones = await locale.listCountriesPhones(); +// Country names will be in French +``` +```client-flutter +client.setLocale('fr'); + +final phones = await locale.listCountriesPhones(); +``` +```client-apple +client.setLocale("fr") + +let phones = try await locale.listCountriesPhones() +``` +```client-android-kotlin +client.setLocale("fr") + +val phones = locale.listCountriesPhones() +``` +```client-react-native +client.setLocale('fr'); + +const phones = await locale.listCountriesPhones(); +``` +{% /multicode %} + + diff --git a/src/routes/docs/products/locale/quick-start/+page.markdoc b/src/routes/docs/products/locale/quick-start/+page.markdoc new file mode 100644 index 0000000000..2d106c5292 --- /dev/null +++ b/src/routes/docs/products/locale/quick-start/+page.markdoc @@ -0,0 +1,182 @@ +--- +layout: article +title: Start with Locale +description: Get started quickly with Appwrite Locale. Learn how to get user location, countries, currencies, and more in minutes. +difficulty: beginner +readtime: 5 +--- + +You can start using Appwrite Locale immediately. The service is publicly accessible and does not require authentication or API keys. + +# Initialize the client {% #initialize-client %} + +First, initialize the Appwrite client with your project endpoint and project ID. + +{% multicode %} +```client-web +import { Client, Locale } from "appwrite"; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); +``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +final client = Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +final locale = Locale(client); +``` +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +let locale = Locale(client) +``` +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Locale + +val client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +val locale = Locale(client) +``` +```client-react-native +import { Client, Locale } from 'react-native-appwrite'; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); +``` +{% /multicode %} + +# Get user locale {% #get-user-locale %} + +Get the current user's location based on their IP address. This returns country code, country name, continent information, IP address, and suggested currency. + +{% multicode %} +```client-web +const userLocale = await locale.get(); + +console.log(userLocale); // { country: 'US', countryCode: 'US', continent: 'NA', ... } +``` +```client-flutter +Future result = locale.get().then((response) { + // Use the locale data + print(response.country); + print(response.countryCode); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +let userLocale = try await locale.get() + +print(userLocale.country) +print(userLocale.countryCode) +``` +```client-android-kotlin +val userLocale = locale.get() + +println(userLocale.country) +println(userLocale.countryCode) +``` +```client-react-native +const userLocale = await locale.get(); + +console.log(userLocale); // { country: 'US', countryCode: 'US', continent: 'NA', ... } +``` +{% /multicode %} + +# List countries {% #list-countries %} + +Retrieve a list of all countries with their names and codes. This is useful for building country selectors and location-based features. + +{% multicode %} +```client-web +const countries = await locale.listCountries(); + +console.log(countries); // { total: 195, countries: [...] } +``` +```client-flutter +Future result = locale.listCountries().then((response) { + // Use the countries list + print(response.total); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +let countries = try await locale.listCountries() + +print(countries.total) +``` +```client-android-kotlin +val countries = locale.listCountries() + +println(countries.total) +``` +```client-react-native +const countries = await locale.listCountries(); + +console.log(countries); // { total: 195, countries: [...] } +``` +{% /multicode %} + +# List currencies {% #list-currencies %} + +Get a list of all currencies including symbols, names, plural forms, and decimal precision. This is essential for building payment and pricing features. + +{% multicode %} +```client-web +const currencies = await locale.listCurrencies(); + +console.log(currencies); // { total: 150+, currencies: [...] } +``` +```client-flutter +Future result = locale.listCurrencies().then((response) { + // Use the currencies list + print(response.total); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +let currencies = try await locale.listCurrencies() + +print(currencies.total) +``` +```client-android-kotlin +val currencies = locale.listCurrencies() + +println(currencies.total) +``` +```client-react-native +const currencies = await locale.listCurrencies(); + +console.log(currencies); // { total: 150+, currencies: [...] } +``` +{% /multicode %} + +# Next steps {% #next-steps %} + +Now that you've started using Locale, explore more features: + +- Learn about [user locale](/docs/products/locale/user-locale) details +- Discover [countries](/docs/products/locale/countries) and [continents](/docs/products/locale/continents) data +- Explore [currencies](/docs/products/locale/currencies) and [phone codes](/docs/products/locale/phone-codes) for international features + diff --git a/src/routes/docs/products/locale/user-locale/+page.markdoc b/src/routes/docs/products/locale/user-locale/+page.markdoc new file mode 100644 index 0000000000..d9b2b6e239 --- /dev/null +++ b/src/routes/docs/products/locale/user-locale/+page.markdoc @@ -0,0 +1,161 @@ +--- +layout: article +title: User locale +description: Get the current user's location based on IP address, including country, continent, currency, and IP information. +--- + +The user locale endpoint provides location information based on the user's IP address. This is useful for automatically detecting user location, customizing content by region, and suggesting appropriate currency or language settings. + +# Get user locale {% #get-user-locale %} + +Retrieve the current user's location information based on their IP address. The response includes country code, country name, continent code, continent name, IP address, and suggested currency. + +{% multicode %} +```client-web +import { Client, Locale } from "appwrite"; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const userLocale = await locale.get(); + +console.log(userLocale); +// { +// ip: '192.168.1.1', +// countryCode: 'US', +// country: 'United States', +// continentCode: 'NA', +// continent: 'North America', +// currency: 'USD' +// } +``` +```client-flutter +import 'package:appwrite/appwrite.dart'; + +final client = Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +final locale = Locale(client); + +Future result = locale.get().then((response) { + print(response.country); + print(response.currency); + return response; +}).catchError((error) { + print(error.response); +}); +``` +```client-apple +import Appwrite + +let client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +let locale = Locale(client) + +let userLocale = try await locale.get() + +print(userLocale.country) +print(userLocale.currency) +``` +```client-android-kotlin +import io.appwrite.Client +import io.appwrite.services.Locale + +val client = Client() + .setEndpoint("https://.cloud.appwrite.io/v1") + .setProject("") + +val locale = Locale(client) + +val userLocale = locale.get() + +println(userLocale.country) +println(userLocale.currency) +``` +```client-react-native +import { Client, Locale } from 'react-native-appwrite'; + +const client = new Client() + .setEndpoint('https://.cloud.appwrite.io/v1') + .setProject(''); + +const locale = new Locale(client); + +const userLocale = await locale.get(); + +console.log(userLocale); +``` +{% /multicode %} + +# Response structure {% #response-structure %} + +The `get` method returns a locale object with the following properties: + +| Property | Type | Description | +| -------- | ---- | ----------- | +| ip | string | The user's IP address | +| countryCode | string | Two-letter country code (ISO 3166-1 alpha-2) | +| country | string | Country name | +| continentCode | string | Two-letter continent code | +| continent | string | Continent name | +| currency | string | Suggested currency code | + +# Use cases {% #use-cases %} + +User locale detection is commonly used for: + +- **Automatic currency selection**: Detect user location and suggest appropriate currency for pricing and payments +- **Content localization**: Customize app content, language, and features based on user location +- **Regional compliance**: Apply region-specific rules, regulations, or content restrictions +- **Analytics and insights**: Track user distribution across countries and continents +- **Default settings**: Pre-fill forms with country, currency, or language based on detected location + +# IP geolocation {% #ip-geolocation %} + +The user locale endpoint uses IP geolocation to determine location. The service is powered by [DB-IP](https://db-ip.com/) and provides accurate location data based on the user's IP address. Note that IP-based geolocation may not always be precise, especially for users behind VPNs or proxies. + +# Multi-locale support {% #multi-locale %} + +You can customize the language of the response by setting the locale. Use the `X-Appwrite-Locale` header or the `setLocale` method in your SDK: + +{% multicode %} +```client-web +// Set locale to French +client.setLocale('fr'); + +const userLocale = await locale.get(); +// Country and continent names will be in French +``` +```client-flutter +// Set locale to French +client.setLocale('fr'); + +final userLocale = await locale.get(); +``` +```client-apple +// Set locale to French +client.setLocale("fr") + +let userLocale = try await locale.get() +``` +```client-android-kotlin +// Set locale to French +client.setLocale("fr") + +val userLocale = locale.get() +``` +```client-react-native +// Set locale to French +client.setLocale('fr'); + +const userLocale = await locale.get(); +``` +{% /multicode %} + +