The process of adapting a web application to run in more than one language is variously referred to as localization or internationalization.
There’s a fair bit of documentation online about localizing/internationalizing CiviCRM, and an active community contributing translations, via a site called Transifex. But most of the available information is geared toward people who are contributing translations to the broader CiviCRM community. If you just need to make some changes to the existing translation files on your own site, perhaps in order to reflect changes you’ve made to the English text via CiviCRM’s Word Replacements feature (Administer > Customize Data and Screens > Word Replacements), then most of it won’t apply to you, as your changes are going to be specific to your own site.
So this is a brief tutorial on that — how to make small local changes, for a single site rather than the whole CiviCRM community. However, you’re still going to need to use Transifex to download the most recent versions of the translation files.
The process of editing the translation files is mostly pretty straightforward, but some parts do involve executing certain commands via the command prompt (if you’re using Windows) or Terminal (if you’re using Mac OS X). If you’re uncertain how to do that, or need a refresher due to being out of practice, here are a few links that may help:
Windows:
Mac:
Linux:
-
If you use Linux, I’m pretty sure you already know how to use a command line! But if by some chance you don’t, try this:
Now, on with the tutorial!
1. Getting the files:
The translations for each language are kept in special files with the extension .po. Unfortunately, you can’t just download them from your web site, edit them on a text editor, and upload them, the way you could with ordinary text or HTML files, because within CiviCRM they’re compiled into a form that isn’t easily editable.
So what you need to do is go to Transifex and create an account (it’s free and fairly quick). Once you’ve created your account (and responded to the verification e-mail the site will send you), go to the CiviCRM section and click on the language whose translation files you want — for example, “French (Canada)”. That’s the one I’ll be using as an example dinuring this tutorial.
You will see a list of the available translation files (23 of them, in the current version, each for a different area of CiviCRM). Unfortunately, there doesn’t seem to be any way to download them all at once — you have to click on each one individually and then click “Download for use” in the little pop-up that will come up for each one.
Yes, having to download one at a time is a big nuisance, but unfortunately, there’s no way around it at present. And you do need to download all of them, even if you’re only making changes to some, because you’re going to have to compile them into one big package containing all the translations once you’re done.
Save all the files into a folder on your own computer.
2. Download and install Poedit:
By far the easiest way to edit the translation files is to use an offline tool like the Poedit program. It’s available for Windows, Mac OS X and Linux. Download whichever version you need (it's free) and install it on your computer.
3. Open the files and start translating!
Launch Poedit, and click on “Edit a translation” on the welcome screen. Choose one of the .po files you downloaded from Transifex. You’ll be presented with a two-column list, with the English strings in the left column and their French equivalents in the right column. Click on any string, and you’ll see two boxes below the listing, within which you can edit both the English source strings and the French translations.
Important note: don’t edit the source strings! Even though Poedit allows it, it’s not something you should actually do, because then CiviCRM will have trouble matching up the translations with the text they’re supposed to be replacing. Even if you’ve made changes to the English text on your site through CiviCRM’s Word Replacements feature, it still uses the original source texts internally, so leave those alone! Just edit the French translations.
If you’re no longer sure which English source strings correspond to which texts on your site because of word replacements that have been made in the past, you can go to Administer > Customize Data and Screens > Word Replacements in CiviCRM to see what the original strings are.
Once you’ve finished making changes to the translation file, save your changes (control-S on Windows and Linux, command-S on Mac). You can then move on to the next translation file, and so on until all your translations are done.
4. Join the files:
This is where it gets a bit more technical, because command-line commands are involved.
Once you are finished making all the changes you want to, you will have to join all the separate .po files togeher into one big .po file, and then compile that into the format CiviCRM needs it to be in, before you can upload it to your site.
First, if you are using Windows, you’ll need to copy all your translation files (yes, all of them, even if there are some that you didn’t make any changes to) to the “bin” directory within Poedit’s Program Files directory. This will normally be located at C:\Program Files\Poedit\bin. If you are using a Mac or Linux, you shouldn’t need to move them anywhere — you can just leave them where they are.
Now, open the command prompt (Windows) or Terminal (Mac) (Linux users probably already know how to get to a command line), and go to the directory where your translation files are. Once you’re there, type “msgcat -o civicrm.po *.po” to join all the translation files together into one big file called civicrm.po. (You could actually do this before editing them, if you want, but the smaller files are generally easier to manage.)
5. Compile the translation:
Type “msgfmt -o civicrm.mo civicrm.po” — that will compile the civicrm.po file into a new format, civicrm.mo, which is what CiviCRM needs.
6. Upload it to your web site:
The last step is to upload it to your web site, into the directory where CiviCRM keeps translations: sites/all/modules/civicrm/l10n/fr_CA in the case of Canadian French (all languages have codes associated with them — two lower-case letters for the language itself, followed by an underscore and then two capital letters for the country whose version of the language you're working with).
That’s it!
If you don’t see your translations right away, you might need to clear CiviCRM’s cache (you can do this by going to Administer > System Settings > Cleanup Caches and Update Paths and clicking the “Cleanup Caches” button), and/or Drupal’s caches (Configuration > Development > Performance and click “Clear all caches”) in order to see your changes.
Resources for further information:
-
Localizing CiviCRM (in CiviCRM User Guide — fairly brief and basic)
-
Internationalization (i18n) (CiviCRM wiki section, providing considerably more detail than the User Guide — in particular, the Resources for Translators and Transifex How-To sections may be helpful to you)
This has been another exciting CiviCRM tutorial brought to you by Freeform Solutions (a not-for-profit organization providing IT consulting to other not-for-profits)
