Serving the world with Appwrite's Locale API

Appwrite strives to be as data agnostic as possible. This doesn't just determine our stance on other programming languages but it also defines our stance on other general languages! 🌍

With Appwrite we give you the tools to succeed writing multilingual projects with ease thanks to the Locale API, so let's get started! 🎉

🇩🇪 Setting a user's Locale

The most important API of the entire Locale Service is the setLocale() API on the client. This API allows you to manually set a user's locale. The best way to use this is to have a language selector somewhere in your application and to use the language List API to get a list of languages to show, then when a user selects a language call the setLocale() API with the country code like so:

sdk.setLocale('de'); // This will change the SDK locale to german

Setting a locale will make a few changes for a user's experience with an Appwrite back-end. Most notably it will change email templates into the user's native language for email verification and password resets:

With locale and Without locale comparison

On the left you can see what happens when we use setLocale and on the right you can see when we don't use setLocale. The email was automatically sent in the user's own language when setLocale was used. setLocale doesn't just affect emails it also affects all API's within the Locale Service, which can be very useful for many things. ❤️

🇺🇸 Getting a user's locale

This is what you will be using to determine the user's country using their IP Address, pairing this with front-end libraries such as Airbnb's Polygot allows you to use your user's home language and change your front-end language to it.

This API call also returns their country code which is ISO 639-1, their continent, a flag 🇬🇧 indicating if they're apart of the EU 🇪🇺 and their currency code which can help with displaying a user's local prices. 💰

GET /v1/locale returns a JSON Response like so:

{
    "ip": "127.0.0.1",
    "countryCode": "US",
    "country": "United States",
    "continentCode": "NA",
    "continent": "North America",
    "eu": false,
    "currency": "USD"
}

🇮🇳 Getting a country list

Dealing with things that require location such as shipping is hard enough without the fact that countries have different names in different languages and users are not always able to distinguish their own countries from a list that isn't in their language. That's where the countries list API comes in! 🦸

This API will return a list of countries with thename being in their own native language, how neat! Each of these also have their code attached which you will be able to use to still determine which country the user is selecting. Using the countries list API is makes it so you have one less thing to think about when it comes to complex localization tasks. 🧠

GET /v1/locale/countries/ returns a JSON Response like so:

"sum": 194,
"countries": [
 {
     "name": "Afghanistan",
     "code": "AF"
 },
 {
     "name": "Albania",
     "code": "AL"
 },
 {
      "name": "Algeria",
      "code": "DZ"
 },
 ...
]

🇪🇺 Getting a list of EU Countries

If you are dealing with countries that are within the EU you are required to deal with data differently and comply with the EU's GDPR Law even if your company is not based in the EU. Appwrite makes this easy thanks to the fact that Appwrite stores a actively updated list of EU Countries for you to easily reference to ensure you are following the correct laws. This can also be useful for redirecting EU users to a EU Specific site.

GET /v1/locale/countries/eu returns a JSON Response like so:

{
    "sum": 27,
    "countries": [
        {
            "name": "Austria",
            "code": "AT"
        },
        {
            "name": "Belgium",
            "code": "BE"
        },
        {
            "name": "Croatia",
            "code": "HR"
        },
        ...
   ]
}

📱 Getting a list of Phone Codes

This one can be particularly useful if you are dealing with any SMS or Shipping information. This API can be leveraged to make it easy for a user to select their phone code while signing for a account or entering shipping information. It also returns the Country Code and Full name with each phone code.

GET /v1/locale/countries/phones returns a JSON Response like so:

{
    "sum": 194,
    "phones": [
        {
            "code": "+1",
            "countryCode": "CA",
            "countryName": "Canada"
        },
        {
            "code": "+1",
            "countryCode": "US",
            "countryName": "United States"
        },
        {
            "code": "+7",
            "countryCode": "RU",
            "countryName": "Russia"
        },
        ...
    ]
}

💷 Getting a list of currencies

Getting a list of currencies can be especially useful for conversion sites or any e-commerce business since it allows people to select the currency they want to use. This list is defined by ISO 4217.

GET /v1/locale/currencies returns a JSON Response like so:

{
    "sum": 117,
    "currencies": [
        {
            "symbol": "$",
            "name": "US Dollar",
            "symbolNative": "$",
            "decimalDigits": 2,
            "rounding": 0,
            "code": "USD",
            "namePlural": "US dollars"
        },
        {
            "symbol": "€",
            "name": "Euro",
            "symbolNative": "€",
            "decimalDigits": 2,
            "rounding": 0,
            "code": "EUR",
            "namePlural": "euros"
        },
        {
            "symbol": "£",
            "name": "British Pound Sterling",
            "symbolNative": "£",
            "decimalDigits": 2,
            "rounding": 0,
            "code": "GBP",
            "namePlural": "British pounds sterling"
        },
        ...
    ]
}

🌐 Getting a list of languages

The list languages API will return a list of languages with a twist. The list it returns will have a nativeName attribute to each of the languages which will give you the language name in the native tongue of that language. For instance nativeName will contain italiano for Italian in a list it could be used to display it like: italian (italiano). Pretty neat right? This API enables you to show a language select for a user in their native language making it easier to select their one. All languages also have their code which is ISO 639-1 so you can easily pass it into setLocale().

GET /v1/locale/languages returns a JSON Response like so:

{
    "sum": 185,
    "languages": [
        {
            "name": "Afar",
            "code": "aa",
            "nativeName": "Afar"
        },
        {
            "name": "Abkhazian",
            "code": "ab",
            "nativeName": "Аҧсуа"
        },
        {
            "name": "Afrikaans",
            "code": "af",
            "nativeName": "Afrikaans"
        },
        {
            "name": "Akan",
            "code": "ak",
            "nativeName": "Akana"
        },
        ...
    ]
}

👋 Conclusion

As you can see the locale API is very useful for making an international site. Giving you access to all localised lists you need to bring to your application to all users of the internet. All responses by the Locale API are localised to the local language if setLocale() has been used or the X-Appwrite-Locale header is set making this very easy to use for all HTTP Clients.

✨️ Credits

Hope you enjoyed this article! We love contributions and encourage you to take a look at our open isuses and ongoing RFCs.

If you can help translate Appwrite into other languages please reach out to us in our support issue!

If you get stuck anywhere, feel free to reach out to us on our friendly support channels run by humans.

Here are some handy links for more information:

Appwrite Contribution Guide

Appwrite Github

Appwrite Documentation

*Taken from internet world stats for 2020