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 Crowdin platform (using their open source 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) and translated using Crowdin. Those files are called message catalogs.
To be available there, they need to be uploaded, something our continuous integration server takes care of in this job. It is triggered when something is changed in the source code. Everyone can then use the Crowdin platform to work on the translations in the Neos project.
The finished translations are then downloaded and put into our version control system, again by a job on our CI server. This job checks the translation platform daily for changes that need to be fetched. Now, head over to the Crowdin sign up and create yourself an account. I'll wait here.
Using Crowdin
The user interface of Crowdin 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 their Interface overview and then work your way through the Translation tutorial.
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 30 languages set up as target languages in the Crowdin projects 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 Crowdin. There might be more projects around, though, for packages not bundled with the Neos base distribution. Just search on Crowdin if you are looking for more to translate…
Roles
When you join the Neos project on Crowdin, you will be aTranslator. This role allows you to create translations and vote on existing suggestions. Every language should have at least one Proofreader. This role allows you to approve translations, allowing them to actually be included in the translated message catalogs.
But since we are still in an early phase (where speed matters and proofreaders are rare), all translations are included for now.
Testing translations
If you have been working on translations in Crowdin, one option is to wait until the CI job fetching them back into the source code has run again and then update. This will only work if you are using the dev-master version of packages, though. If you do not have the option to do that, you can instead use the Neos demo to check your translations.
Another option is to download the translations from Crowdin and unpack them manually into your local project. To do this, just look for the Download button on Crowdin and unpack the downloaded archive over your 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 Crowdin on those XLIFF files? To get you started, here is an introduction into the most important things you need to know.
Workflow
The translations in a package are contained in XLIFF files (here is an example) and translated using Crowdin. Those files are called message catalogs.
To be available there, they need to be uploaded, something our continuous integration server takes care of in this job. It is triggered when something is changed in the source code.
Everyone can then use the Crowdin platform to work on the translations in the Neos project.
The finished translations are then downloaded and put into our version control system, again by a job on our CI server. This job checks the translation platform daily for changes that need to be fetched.
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 pushed to Crowdin automatically as described above.
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 Crowdin, you can download the translations from Crowdin and unpack them manually into your local project. To do this, just look for the Download button on Crowdin and unpack the downloaded archive over your installation. Now the latest XLIFF files are available locally.
Using Crowdin for your own package
Crowdin can be used for any other Flow package just fine. And you can use the tooling we created for our purposes as well. The BuildEssentials package (most probably you have it installed via composer anyway, it is named typo3/buildessentials) contains a folder Crowdin with some helper scripts. Just follow the instructions in the README.rst file.