Here's how I implemented a translation management system for a static website, using GNU gettext. For the impatient, I've distilled it to 11 instructions at the end.

This system allows block-by-block translation (string-by-string), which is better than page-by-page because:

• Changes to non-translated parts will be applied to all translations automatically (formatting, tags, images, maybe dates, names, links, etc.).
• By storing the text blocks of all pages together, repeated blocks will only have to be translated once (menu text, copyright notices, headings, etc.).
• You won't get lost when the original changes while the translation is still in progress.
• When you change a paragraph in the original, it's easier to see what parts of the translations need to be updated.

For such a system, the abstract steps are:

Gettext seemed like an obvious possibility, and everything's working perfectly now, but it took me eight hours. The difficulty was that the existing documentation is all geared toward using gettext for computer programs, not for websites or documents. That's when I realised that I must document what I did:

I started by minimally turning my webpage into a computer program. This involved five steps:

Gettext works with lots of programming languages, so take your pick from the examples that come with the package. On my computer, these are in this folder:
/usr/share/doc/gettext-doc/examples/
The choice of language isn't important. The code will be dead simple.

Here's my original index.html:

Of the supported programming languages, I choose Scheme (a dialect of Lisp). At first glance, the code below looks complex, but you'll only have to modify the first and third chunks. The first chunk defines three variables which should be self-explanatory. All the webpage text is in the third chunk. It's broken up into blocks and I've put gettext tags for Scheme (_ ) around the translatable blocks. Here it is, generate-index.scm:

Three of the eight strings are marked as translatable. The other five are part of the shared frame that will be the same no matter what language version of the page is being generated.

Remember to replace any quote marks in your HTML with backslash-quote (\"), and to add a few line breaks (\n) to make the output readable. Those are the quote and the newline sequences for Scheme. They're the same in a few other languages, but they're different in others.

Before you continue, you must set the "build-directory" variable to the directory where generate-index.scm is. If you don't, everything will seem to work but your program will never access the translated strings.

That done, you extract the translatable strings with these two commands:

• $ xgettext --language=scheme -d ciarans-website -k_ generate-index.scm

• $ mv ciarans-website.po ciarans-website.pot

And then you can create a file (a "po" file) for French translations with this command:

• $ msginit --locale=fr

One part of the gettext manual says that "msginit" is optional - that you can do it manually instead, but this didn't work for me at all. I spent two hours diagnosing that problem. Use msginit.

This creates fr.po which you can edit with any text editor. There will be a line at the top like this:

If your charset is "ASCII", you should probably change it to UTF-8. If your charset is something else and you get error messages from other gettext tools (such as msgmerge) about invalid characters, then changing charset to UTF-8 might also be the answer. There'll also be a field for content-transfer-encoding. The manual says that should always be "8bit".

Emacs is particularly good for editing po files because it has a special editing mode for them.

And then you have to convert your po file into the special mo format and put it in the subdirectory where gettext expects it to be with these two commands:

• $ mkdir -p fr/LC_MESSAGES

• $ msgfmt --output-file=fr/LC_MESSAGES/ciarans-website.mo fr.po

Make the Scheme file executable, and that's it!

Ok, so there's your proof-of-concept. Next, I have to convert my site to this system and maintain it (using msgmerge). I'll try to keep notes to publish here.

-- 
Ciaran O'Riordan, (RSS)
Support free software: Join FSFE's Fellowship