Managing static message translations with Crowdin
If your site takes advantage of Craft’s static message translations feature, you can improve your translation workflow using Crowdin. Crowdin provides a platform for collaborating on translations, and also integrates with professional translation services such as Alconost, Gengo, and Acclaro.
We use Crowdin + Alconost for Craft’s own control panel translations.
Project Setup #
Before you can start managing translations with Crowdin, you’ll first need to set up a source translation file in your repo.
Typically static message translation use the source language messages as the message “keys”, for example:
{{ "Contact Us"|t }}
However, Crowdin is expecting that the message keys are just that—only keys—and you must explicitly tell it what those keys’ source translations are.
To do that, create a new file located at /translations/<source-language>/site.php, which maps your message “keys” with their “source translations”. For example:
<?php
// -- translations/en/site.php --
return [
'Contact Us' => 'Contact Us',
'News' => 'News',
'Open Hours' => 'Open Hours',
'Privacy Policy' => 'Privacy Policy',
'Terms of Use' => 'Terms of Use',
];
If you prefer, you can start defining your translation keys as actual keys (e.g. contact_us), and referencing those in your templates instead of source translations:
{{ "contact_us"|t }}
Next up, you’ll want to add a new crowdin.yml file to the root of your repo, which tells Crowdin where your source translation file is, and how it should be mapped to the target translation files:
files:
- source: /translations/<source-language>/site.php
translation: /translations/%two_letters_code%/site.php
source should be the hard-coded path to your new source translation file.
When Crowdin is syncing and saving new translations, it will swap that %two_letters_code% token in the translation setting with the target language’s two-letter code (e.g. nl).
If your site needs to be translated into specific locales (e.g. en-US and en-GB), then use %locale% instead. Note that if you do this, you’ll need to make sure that all of your sites’ Language settings are set to specific locales as opposed to two-digit language codes.
Commit your source translation file and crowdin.yml, and push them up to your remote repo.
Finally, you will need to create a new Git branch, which Crowdin will use to create pull requests from, when new translations are ready to be merged into your project. By convention it should be named after the source branch that Crowdin should be pulling existing translations from. So for example if you want Crowdin to pull translations from your master branch, then your new branch could be called l10n_master (“l10n” is shorthand for “localization”).
Create the Crowdin project #
Now you’re ready to move your project into Crowdin. Create an account, and then click on the Create Project button. You’ll be taken to the project setup page. Give your project a name, choose the source language, and pick which languages it should be translated into.
Once you’ve created your project. you’ll be taken to its dashboard.
Connect Crowdin to your repo #
The last step is to connect your new Crowdin project to your Git repository. To do that, click on the Set Up Integration button at the bottom of your dashboard.
Follow one Crowdin’s guides to complete the Git integration, depending on where your repository is hosted:
Once you’ve completed the Git integration, Crowdin will sync your project with any existing source/target translations, and you’ll be ready to roll.
As changes are made within Crowdin, you’ll start receiving pull requests on your remote repo with all the latest translations.
