Internationalization

The ARN Server includes and exposes an internationalization (i18n) API that allows you to upload and download translations.

Configuration

The translations are stored in the database using a data service configuration.

The i18n configuration includes the following property:

• data: The configuration of the data service used to store translations.

For example, your configuration can have an i18n property with the following value:

{
  "data": {
    "uri": "mongodb+srv://maxime:[email protected]/arn-server-test-dev",
    "collection": "arn_data",
    "path": "/i18n"
  }
}

If you want to synchronize your translations with a Lokalise project, you can include the following additional properties:

• secret: The secret API key required for translation updates.
• downloadBaseUrl: The URL to download new translations from.

Data Storage

Once the i18n configuration is set, translations should be uploaded to the specified collection/path in the database. For example, using the sample configuration above, you could store the following translations under the i18n path of the arn_data collection:

{
  "fr": {
    "welcome": "Bienvenue !"
  },
  "it": {
    "welcome": "Benvenuto !"
  },
  "en": {
    "welcome": "Welcome!"
  }
}

You can structure your translations as nested objects based on your needs and fetch the required level of translations from the client side.

REST API

The i18n API provides the following endpoints:

Fetching Translations

GET /:projectKey/i18n/:path retrieves the existing translations as a JSON payload. The language of the returned translations is determined by the Accept-Language header in the request. If the specified language is not found in the i18n database, a 404 Not Found response will be returned.

📌

The Accept-Language header is automatically sent by browsers and reflects the user's language preference more accurately than navigator.language.

Fetching a Subset

The path parameter is optional, but if provided, it allows you to fetch a specific subset of translations. This can be useful for optimizing your application by requesting only the necessary translations. For example, if your app starts with a welcome page, you can request only the translations for that page and avoid downloading translations for the entire app.

Uploading Translations

POST /:projectKey/i18n/ is a Lokalise-specific route that expects a webhook event record for the project.exported event. Alternatively, you can update the raw translation values using a POST data request and the data path specified in the i18n configuration.

By default, this route requires a project admin x-api-key for authentication.

💡

• Since translations are handled as data, you can also update translations through ARN Admin by updating the corresponding data.
• The Accept-Language header sent by browsers can be used to automatically determine the user's language preference for translations.

🚀

Feel free to explore the ARN Admin tooling for an alternative way to upload translations easily.