Translating Neos

Accessibility and translations are key factors for every major product - We always strive to make Neos as international as possible

Translations for your language are missing? We would love if you would help us make Neos better!


The translation process

The user interface of Neos (like all software based on the Flow Framework) is translated using message catalogs in the XLIFF format.

While XLIFF–being based on XML–can be edited by hand, this is not really the best way to work on actually translating a lot of text. Thus we use the web-based Weblate platform (using their Libre plan, so thanks to them!) to translate the message catalogs in the packages that make up Neos.


You are a translator

It is great that you want to help with translating the Neos user interface into your language! To get you started, here is an introduction into the most important things you need to know.

Workflow

Technically, Neos is not one monolithic system, but made of a number of independent packages. This means, that translations are spread over those packages as well. The translations are contained in XLIFF files (here is an example). Those files are called message catalogs and are fetched automatically by Weblate. Everyone can use the Weblate platform to work on the translations in the Neos project. The finished translations are synced back into our version control system. Now, head over to the Weblate sign up and create yourself an account. I'll wait here.

Using Weblate

The user interface of Weblate seems rather easy to use, but to learn about the features and not miss on some helpful tricks, you should read their documentation. We suggest to start with Translating using Weblate and then work your way through the remaining documentation as needed.

Languages

Currently Neos come with some languages pre-configured for the users to select from (Dansk, Deutsch, English, Español, Français, Latviski, Nederlands, Polski, Pусский, Svenska), but we have more languages set up as target languages in the project we maintain.

English is a bit special, since it is also the source language for translations, meaning it is the language any labels are created in first. If your language of choice is not available as a target language, get in touch with us to have it included. As soon as a target language has made sufficient progress, it will be included in the out-of-the-box settings in Neos.

All available translations are shipped with Neos, so even if your language is not among the ones enabled by default, you can still add it via configuration (look for availableLanguages in the Neos settings.)

Projects

As mentioned, Neos is made of of several individual packages. To make your life easier, we put all the message catalogs into a single project on Weblate. There might be more projects around, though, for packages not bundled with the Neos base distribution. Just search on Weblate if you are looking for more to translate…

Testing translations

If you have been working on translations in Weblate, one option is to wait until they were fetched back into the source code and then update. This will only work if you are using the devevlopment version of packages, though. Another option is to download the translations from Weblate and unpack them manually into your local project. To do this, just look for the "Download translation files as ZIP file" link on Weblate and use the downloaded archive to update your local Neos installation. Now the latest XLIFF files are available locally.

Communication

In our community platform we have created a category to discuss translation related issues. That can be anything from the best word for a specific case to global agreement on terms in the project glossary. Make yourself heard!


You are a developer

You have a Flow package that you want to translate? And you wonder how to use Weblate on those XLIFF files? To get you started, here is an introduction into the most important things you need to know.

The translations in a package are contained in XLIFF files (here is an example) and can be translated using Weblate. Those files are called message catalogs. To be available there, a project has been set up that syncs with the Git repository of our package(s).

Creating XLIFF sources

To make your code fit for translation, you need to replace any hardcoded output with translations and create an english message catalog that contains the source for all those translations. More information on XLIFF message catalogs is available in the Flow documentation.

Updating XLIFF sources

If you add something to a package that already has message catalogs, just look for the most appropriate place to add your label. Follow the pattern in the existing files when it comes to identifier assignment and just update the english XLIFF file with any new labels you need.

For packages that are part of the Neos and Flow base distributions, the changes will be synced to Weblate automatically as described above.

Be aware that you can add a translation (in addition to the english XLIFF catalog additions you do) in a PR – but missing translations will be added automatically by Weblate after the PR is merged. As usual the needed updates will "work their way through the branches" when we do upmerges.

Testing translations

If you work on your translations locally, by editing the XLIFF file manually or with the help of some other tool, you can see the results directly.

If you want to test the results of translating on Weblate, you can download the translations from Weblate and unpack them manually into your local project. To do this, just look for the "Download translation files as ZIP file" link on Weblate and unpack the downloaded archive to update your installation. Now the latest XLIFF files are available locally.

Using Weblate for your own package

Weblate can be used for any other Flow package just fine. Take a look at these instructions on  setting up projects on Weblate to get started.