Internationalization

Corteza allows you to fully translate most aspect of the system. From the user interface to custom Low Code configurations such as modules and their fields.

User interface translations are provided via static .yaml files, which are bundled into the corteza-server docker image.

If you wish to upload additional or modified translations, you need to do some server-side configuration.

Configuring the System

Applying the following steps allows your Corteza instance to serve customized translations.

Corteza ignores translations for languages that are not defined in the .env file. See managing languages for details.

Preparing the File Structure

Create a new directory on the server running Corteza.

Lets assume the file structure looks like this:
📁 my-corteza
  📄 docker-compose.yaml
  📄 .env
  📁 my-locale (1)
    📁 src (2)
1 We use the my-locale directory to hold our custom translations and any corresponding metadata.
2 The src directory holds the translation files and appropriate configuration files.

System Configurations

Firstly, define the volume in your docker-compose.yaml file. An example following the above file system would look like this:

version: '3.5'

services:
// ...
// Additional services here
// ...

  server:
    image: cortezaproject/corteza:${VERSION}
    restart: always
    env_file: [ .env ]
    depends_on: [ db ]
    volumes: ["./my-locale:/my-locale"] (1)
    // ...
    // Additional configurations here
    // ...

// ...
// Additional services here
// ...
1 This is where you mount the volume.

Secondly, you need to tell Corteza where the translations are located at. This is done by the LOCALE_PATH .env variable. An example following the above setup would look like this:

// ...
// Additional configurations here
// ...

LOCALE_PATH=../my-locale/src (1)

// ...
// Additional configurations here
// ...
1 This is where you define the path. If you wish to define multiple paths, use the colon (:) as the delimiter. To exemplify; LOCALE_PATH="../my-locale-en/src:../my-locale-de/src". When multiple paths are used, defiitions are overriden in the same order as defined.

Applying Changes

After all of the configuration is in place, you need to reload the configurations.

Run:
docker-compose up -d

If you update translation files after Corteza server started, you must restart it.

Run:
docker-compose restart

Managing Available Languages

The languages that you wish to support by your Corteza instance must be defined by the LOCALE_LANGUAGES .env variable.

The language tag must follow the BCP-47 standard. An extensive list of languages is available here.

Languages can be defined using a simple language tag, such as en and sl. If you need to be more specific, you can use a region suffix, such as en-US and en-UK. Corteza tries to detect the language from the request headers and serve appropriate translation.

If you want to define multiple languages, you need to separate them with a comma (,).

An example configuration that uses English, German, and Italian languages:
LOCALE_LANGUAGES="en,de,it"

Development Environment

Corteza provides some helpful utilities for debugging and general translations, which can be enabled with the following .env variables.

Variable Description

LOCALE_LOG

The LOCALE_LOG variable makes the Corteza server output logs of what is happening in the system. This can help you debug issues.

LOCALE_DEVELOPMENT_MODE

The LOCALE_DEVELOPMENT_MODE variable makes translation modifications easier, as the translation files are loaded for each request instead of at boot-time.

Troubleshooting

Language Not Loaded as Expected?

When languages do not load as expected, enable logging and restart the server. First few log lines should describe what is going on and what languages are loaded.