-
Notifications
You must be signed in to change notification settings - Fork 93
Translation for Skosmos 3
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 code, Vue i18n is used (WIP, see #1523)
- 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.
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.
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.
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.
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.
When you have permissions to edit translations, just add all the translations necessary for your language.
When the translation is complete (or nearly so), you can pull the translations from Lokalise into your local Skosmos installation:
bin/console translation:pull lokalise --domains messages --format json --force --locales 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.
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.
bin/console translation:extract --dump-messages en
(should be shown in the list) or
bin/console debug:translation en
(should show it as missing)
bin/console translation:extract --force en --format json --prefix ""
bin/console translation:push lokalise --domains messages --locales en --force
bin/console translation:pull lokalise --domains messages --format json
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.
This command shows unused messages:
bin/console debug:translation en
TBW: how to remove unneeded messages from the translation files and from Lokalise