I have been meaning to write about this topic for a while now. All the bits have been waiting for the right moment to be assembled. For several years, have been working with the Conseil scolaire francophone de la Colombie-Britanique (BC Francophone School Board) in developing and maintaining their job board application (https://emploi.csf.bc.ca/). I know, I know, it doesn't look very innovative from the outside, but there are some very useful admin tools in the back end. It's true, I swear.
As the site is built for francophones, all the content needs to be available in French. I have put together a simple step-by-step recipe for module creators and translators who need to have their site in a language other than English. Even if you have no immediate need for a translation of your module, providing a translation template will allow other contributors to create their own translations. Note that this recipe is Drupal 5-specific but doing this for Drupal 6 would be very similar.
Getting going and generating the PO Template
Generating the POT file is the minimum you can do - beyond not doing anything at all. This is the template from which all of your module translations will stem.
- First off, you will need to get the the potx module (http://drupal.org/project/potx) and the gettext package (http://www.gnu.org/software/gettext/#TOCdownloading).
- From the potx module folder, copy potx-cli.php and potx.inc to your module directory.
- Navigate to your module directory and create a folder named po.
- Make sure that potx-cli.php is executable [ $ chmod +x potx-cli.php ] and execute it [ $ ./potx-cli.php ].
- This will generate a template file named general.pot - a PO Template file.
- Move the newly created .pot file to your po directory and rename it with your module name while keeping the .pot extension.
Creating a PO file
If you need or want to translate a module (your own or someone else's) you will need to generate a PO file out of a PO Template. The PO file is the file that will actually hold your translated strings. This is how you can do it:
- Navigate to the po subfolder of the module folder. There you should see the .pot file and maybe some .po files, if translations already exist. If your language PO file is there, well, you're in for the easy ride. You may pass go and collect your dough. If not, it's gonna take another turn...
- Generate an empty PO file using the msginit utility [ $ msginit --locale=ll_CC ] where ll_CC is the locale (ll the language code like “fr” and CC the country code, like “CA”). From what I gather, you may simply use the the language code. For example [ $ msginit --locale=fr ].
- If all goes well, you should now have a PO file (per the above example we would have fr.po). Now is the time to put your translator skills to work.
Keeping your POT in the game
As your module evolves, translatable strings may be added, removed or simply moved. In order to keep your translations up-to-date, you will need to keep your POT up-to-date.
- Go to your module directory and generate a new POT file per the steps described above.
- Copy the new POT file over the one in the po folder.
- Use the msgmerge utility to generate a new PO file that merges the “structure” of the template and the existing translations [ $ msgmerge -U def.po ref.pot ]. The -U flag is for update; the def.po is your existing PO file and ref.pot is the new POT file. Msgmerge should create a backup of your PO file (look for a PO file followed by a tilde ~). But, until you can confirm that your version of msgmerge does it for you, I'd recommend making a backup copy yourself.
There you are! Translating Drupal modules is no longer a secret for you. Now getting the translation right can be another challenge!
Oh. last words of advice: use English in your module and wrap your strings with the t() function, otherwise gettext/potx-cli.php will not pick up your strings.
