Locales

PILOS is available in multiple languages. By default, PILOS comes with English and German translations. Other locales are maintained by the community using PoEditor.

Locale structure

Locales are stored as php arrays in the lang folder. Each locale has its own subdirectory named after the locale code (e.g. en). Within the directory each group has its own file (part before the first dot in the translation string), e.g. 'app' or 'auth'. For example, the string auth.ldap.username_help would be stored in the file auth.php.

Within the file, the keys are organized in nested php arrays.

Overriding locales

You can override the default locales by creating custom locale files in the resources/custom/lang directory. This directory need to be mounted to the container by adjusting the docker-compose file.

- "./resources/custom:/var/www/html/resources/custom"

The locales are merged during runtime, so you only need to define the keys you want to override.

Example

To override the LDAP username help text in the english locale, create a custom locale file resources/custom/lang/en/auth.php:

<?php

return [
    'ldap' =>  [
        'username_help' => 'My custom help text'
    ]
];

To customize the date time format and the display name of a locale create a json file metadata.json in the locales directory.

{
    "name": "German",
    "dateTimeFormat": {
        "dateShort": {
            "year": "numeric",
            "month": "2-digit",
            "day": "2-digit"
        },
        "dateLong": {
            "year": "numeric",
            "month": "short",
            "day": "2-digit"
        },
        "time": {
            "hour": "2-digit",
            "minute": "2-digit",
            "hour12": false
        },
        "datetimeShort": {
            "year": "numeric",
            "month": "2-digit",
            "day": "2-digit",
            "hour": "2-digit",
            "minute": "2-digit",
            "hour12": false
        },
        "datetimeLong": {
            "year": "numeric",
            "month": "short",
            "day": "2-digit",
            "hour": "2-digit",
            "minute": "2-digit",
            "hour12": false
        }
    }
}

New locales

To add custom locales that are not part of the core, add them to the resources/custom/lang directory. This directory need to be mounted to the container by adjusting the docker-compose file.

- "./resources/custom:/var/www/html/resources/custom"

You need to create all php files and metadata.json file. Any missing keys will be filled with the default english translation. To enable the new locale, you need to add it to the ENABLED_LOCALES in the .env file.

Locale caching

For better performance, locales are automatically cached in production when the container is started.

To manually cache the locales, run the following command:

docker compose exec app pilos-cli locales:cache