Internationalization

Internationalization (i18n) is a solid part of Axe API to provide multi-language support to your API. In this section, we are going to try to explain how it works.

• You will learn
• What internationalization?
• How Axe API handles it?
• How to configure it?
• How do HTTP clients decide the language?
• How does Axe API manage the content?

i18n

Internationalization (i18n) in REST APIs refers to the practice of designing APIs to support localization and language-specific content. It involves creating APIs that can handle multilingual data, adapt to different cultural conventions, and provide responses in the user's preferred language.

APIs can achieve i18n by incorporating language tags, enabling language negotiation, providing localized error messages, and offering language-specific content.

Internationalization in REST APIs ensures a seamless user experience across different regions and cultures, allowing applications to cater to a global audience and support diverse language requirements.

Axe API approach

Axe API provides the fundamentals of internationalization (i18n) by handling the current language selection process.

Since Axe API is Rest API Framework, it does NOT have any user-related content except form validation messages. As the Axe API Core Team, we believe that giving developers freedom is more important than building an all-in-one framework.

In this section, you may find everything about internationalization.

Configuration

As a developer, you are able to define which languages are supported in the app/v1/config.ts file, with the default language like the following example.

TIP

Since the configuration file is version-based, you are able to provide different languages on different versions if you want.

That helps to add multi-language support in the future when if you don't want to support it in the first place.

const config: IApplicationConfig = {
  supportedLanguages: ["en-GB", "en", "de"],
  defaultLanguage: "en-GB",
};

TIP

You should use the ISO 639-1 Standard in configurations.

You should pick a default language, and also the supported languages as an array.

Setting the current language

Clients are able to select the preferred languages by Accept-Language request HTTP header. Please check the following example out.

Accept-Language: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5

Basically, we define that to see the content in fr-CH (Swiss French) with this HTTP Header. Also, the client is accepting to see the content in any other language in case fr-CH is not supported by the API. q= parameter is refer to priority.

TIP

You can find more in the Accept-Language documentation.

Axe API analyzes the Accept-Language HTTP header and decides in which language the content will be presented. Also, it uses the defaultLanguage value if there is no matched language between the client and the server.

This is a very efficient way to determine which language will be used with the HTTP context.

Current language

Axe API carries the currentLanguage value in all HTTP Request-Response cycles. Anywhere in the code, you can access the currentLanguage value via AxeRequest object.

import { IContext } from "axe-api";

const onBeforeInsert = async ({ req }: IContext) => {
  console.log(req.currentLanguage);
};

export { onBeforeInsert };

The currentLanguage type is look like the following interface;

interface ILanguage {
  title: string; // Full title of the language code, en-GB
  language: string; // Short title of the language code: en
  region?: string | null; // Regional title of the language code: GB
}

TIP

You can import this interface from axe-api like the folowing example;

import { ILanguage } from `axe-api`

Form validation messages

As a developer, you don't have to do anything for the form *validation messages**. i18n structure works perfectly with form validation messages. The form validation message language will be set automatically by the client's **HTTP Request Header**.

For example, if you want to support German in your application, you should configure your files like the following examples;

app/v1/config.ts

const config: IApplicationConfig = {
  // ...other configurations
  supportedLanguages: ["en", "de"],
  defaultLanguage: "en",
};

The form validation messages will be shown in German if the client sends an HTTP request like the following one;

$ curl \
  -d '{"name": "", "surname":""}' \
  -H "Content-Type: application/json" \
  -H "Accept-Language: de" \
  -X POST http://localhost:3000/api/v1/users

This is the HTTP response example;

{
  "errors": {
    "email": ["Das email Feld muss ausgefüllt sein."],
    "name": ["Das name Feld muss ausgefüllt sein."],
    "surname": ["Das surname Feld muss ausgefüllt sein."]
  }
}

TIP

You can find all the supported languages from validatorjs via here.

HTTP response header

Axe API adds the Content-Language HTTP headers to the responses.

This is an example result;

Content-Language: en-GB

You can use this value to understand which language has been selected as the language in an HTTP request.

System Messages

Axe API may throw many system errors for developers. These messages will not be able to translate due to they are not related to users.

Next step

In this step, we've learned many things about the configuration. In the next step, we are going to talk about how you can manage errors.