How to translate Skosmos to a new language, or to edit existing translations

Translations for Skosmos user interface strings are managed in two different ways, for different languages:

• "Core" languages maintained by the National Library of Finland (Finnish, Swedish, English), the translations are maintained using Poedit and using it to edit po files directly.
• Contributed languages (all others), the translations are maintained on the Transifex platform.

Translating to a new language

To translate to a new language, you need to:

1. Register as a user on Transifex
2. Check the Skosmos project page on Transifex to see if your language is already there

• if it is, you can request to join the translation team. The request should be immediately accepted.
• if not, you can request a new language to be added. This might take a few days.

3. Once the target language exists and you have been approved as translator, you can start translating messages into your language (click on "Translate" and select the target language and the resource "skosmos_en.po").

• You can ask for help on the skosmos-users mailing list / web forum if necessary.
• Be sure the check the translation instructions for each message, these have been provided for some messages that have previously been difficult to translate. In the translation view, the instructions are just above the box where you enter the translation.

4. Once your translation is ready, ask for it to be integrated into Skosmos (open an issue here on GitHub). If you are a developer, you can try it out for yourself like this:

• download the messages from Transifex using the "download for use" link
• save the file as resource/translations/skosmos_XX.po where XX is your ISO 639-1 language code
• run the compile-translations shell script to compile the messages into a mo file
• add the new language to config.ttl so it gets used
• make sure that you have the locale for your language installed (check locale -a output); if not, you should install it (e.g. "sudo locale-gen xx-XX.utf8")
• restart Apache (so the gettext cache gets cleared)

Translation basics (under the hood)

Translations for user interface elements are implemented using gettext. The translations and locales to use in a particular installation are defined by the LANGUAGES setting in config.ttl; see Configuration for details.

Using Poedit

Translations can edited using Poedit.

• Install Poedit in Debian/Ubuntu: apt-get install poedit
• Install Twig Gettext Extractor to let Poedit parse translatable strings from Twig templates.
  • Install it using Composer by running this command in the root of the Skosmos code repository: php composer.phar install
• Set up Poedit to use the extractor following the installation instructions on the Twig Gettext Extractor home page, except use tools/twig-gettext-extractor as the path because we need to use our customized version of this script due to our custom Twig filters.

In Poedit, you can then update the catalog (i.e. extract all translatable strings), edit the translations for each language, and save the results.

Adding new strings to translate

If the word you want to translate can't be found in the .po files you will need to add {% trans %} and {% endtrans %} tags to the object to be translated in the twig templates. After that you can add the word to the .po file with its translation.

Translatable strings not present in templates or code

Some strings to be translated do not naturally appear in the Twig templates or PHP code, e.g. SKOS qnames such as skos:broader. Such strings are listed in the Twig template extra_msgids.twig which is not actually used by Skosmos for rendering, only for feeding the extra messages to xgettext/Poedit.

Updating existing translations

The translations are located in .po files under resources/translations/

For example if you want to make changes to the Finnish translation of Skosmos the file you will need to update is skosmos_fi.po.

Using the updated translations

After you have made the desired changes to the .po file you will need to run the translation script compile-translations (known as trans_script in older Skosmos versions) located in the same folder e.g., in Ubuntu with command sh compile-translations. The script creates the machine readable .mo files and moves them to the corresponding folders. Finally it restarts the local Apache server so you can see your changes immediately without any cached results.