Translation of the Skosmos 3 user interface is handled using the following infrastructure:

• In the Skosmos PHP backend, translations are managed using Symfony Translation.
• In the frontend JS code, a custom built translation service is used
• To manage the translations to different languages, we use the Lokalise platform.

The base/default language for all messages is English, so messages in the Skosmos codebase (e.g. Twig templates and Vue templates) are generally in English (with a few exceptions that are English-derived IDs). Translations to all other languages are maintained using Lokalise.

In the Skosmos application code, translations are saved in JSON files under resource/translations. The files are named messages.XX.json, where XX is the BCP47 language code. These files are not intended to be edited manually; instead, the translation commands in the Symfony command line console should be used to manage them.

How to use Lokalise

Getting access

In order to start using Lokalise to manage translations, you need to be added as a Contributor to the Skosmos-3 project. Ask for an invite!

Contributors can have different access levels and specific rights for particular languages. A typical translation contributor will have read access to all languages and write access to one or two selected languages that they help maintain.

Editing existing translations on Lokalise

Open the Skosmos-3 project. You can edit the message translations under the Editor tab. It's possible to select either Bilingual or Multilingual view. The recommended way is to select Bilingual view with English in the left column and the target language in the right column.

See the onboarding guide for more assistance and tips.

Translating Skosmos to a new language

Target audience: users who want to use Skosmos in their own language

Adding a new project language

The first step in translating Skosmos to a new language is to add that language into the project on Lokalise. Adding a language requires administrative permissions and is done like this: in the Editor tab, change to Multilingual view, open the dropdown list of languages and select the last option "Add language". Choose the language(s) to be added and click Add.

If you're a regular contributor, you will need to ask an administrator to add the language and to give you write permissions to that language.

Translating to the new language

When you have permissions to edit translations, just add all the translations necessary for your language.

Adding the new language to the Skosmos codebase

When the translation is complete (or nearly so), you can pull the translations from Lokalise into your local Skosmos installation:

bin/pull-translations XX

where XX is the language code for your language.

To test the new translations in Skosmos, you have to enable the new language in the Skosmos configuration. See the skosmos:languages setting under Configuration.

Maintaining translations when the code changes

Target audience: Skosmos developers

When the Skosmos code changes, the translations need to keep up. The way to ensure this is to extract the messages from the codebase and synchronize the changes to Lokalise, then pull back the translations from Lokalise to the codebase.

Enabling Lokalise push access

If you have write access to the English language (i.e. you are a core Skosmos developer), and need to perform push operations (see below), you will have to add a Lokalise authorization token for Symfony Translations. To generate the token, click on your profile image in Lokalise (bottom left corner), select "Profile settings", change to the "API tokens" tab and click on "Generate a token". Select the "read and write access" token type. Copy the generated token and save it in into a file called .env.local with the root directory of your Skosmos development installation (the .env file already contains a token with read-only access) in a format like this:

LOKALISE_DSN=lokalise://8890111966276e3b27f4e6.81990707:XXXXXXXX@default

where XXXXXXXX is the token.

How to mark messages to be translated in the Skosmos codebase

Twig templates

Use the trans filter to translate the message, e.g. {{ "Hello world!" | trans }}

Vue components

1. Add a declaration that $t is a global function, e.g. /* global Vue, $t */
2. Put the Vue component initialization inside a function body, so it can be initialized only after the translation service is ready
3. Create a computed method for each message that needs to be translated, returning $t("message to translate")
4. Use the computed method values within the Vue component
5. Add a waitForTranslationServiceXXX method that calls the component initialization function (step 2) after the translation service is ready

Plain JavaScript

TBW

Special case: messages from variables

Sometimes the message isn't a literal string in the template, but comes from another source as a variable value. For example in Twig templates, a variable can also be used with the trans filter, e.g.: {{ error_message | trans }}

To make sure that these messages are also translated, they can be added to the extra-msgids.twig template. This is a special Twig template that is never rendered by Skosmos, but the messages inside will be extracted just like those from other Twig templates, so that they are kept in the translation files.

When new messages are needed

1. Make a change in the code that adds a new translated message into the twig templates

Edit a Twig template or Vue component and add a message that needs to be translated.

2. Check that it can be extracted from the code:

bin/console debug:translation en

(should show it as missing)

If you can't find the new message in the output of the above commands, make sure that you have marked the message as requiring translation (see above section) and try again.

3. Extract the message(s) and add them to the English language translation file:

Run this command:

bin/extract-translations

This will add the new messages into the English language translation file messages.en.json, which is used as the basis for translation into other languages.

Check using e.g. git diff that the messages that you expected were added into the file.

4. Push the translation file to Lokalise:

When your code change is getting ready for PR review, you should push the message files with the new translations to Lokalise.

Run this command:

bin/push-translations

5. In the Lokalise UI, look up the message and add translations in other languages

Skosmos core developers are responsible for translations to Finnish, Swedish and English. English translations are usually not needed because the message itself is already in English in most cases.

Add translations to these languages in the Lokalise UI.

6. Pull the translations back to the codebase:

Run this command to pull the translations back to the Skosmos codebase:

bin/pull-translations

Check that you got the translations (e.g. using git diff) into the message files and include them in the final pull request.

Note! It is possible that a key-value pair removed in Lokalise does not get deleted from the local English (default) language file as a result of the pull command. In that case the --force option could be used to remove the key-value pair, but it would delete all the pairs where both the key and value are the same (e.g. 'Error': 'Error'). Therefore, it is better to manually remove from the local file any key-value pairs that have been removed in Lokalise. The issue is known and a solution will be sought later.

Removing obsolete messages

This command shows unused messages:

bin/console debug:translation en

Obsolete messages need to be removed manually both from Lokalise and from the messages.en.json file:

1. To remove a message from Lokalise, use the UI functionality (hover over the key to show action icons, click on the Delete icon). This will remove both the (English language) key as well as all its translations to all languages.

2. To remove a message from messages.en.json, simply edit the file and drop the line(s), making sure not to break the JSON syntax.