Is gettext appropriate for internationalizing user help documentation?

Question

On my project, we have po files to internationalize/translate various labels, error messages, button-text etc. We also have separate po files for the entirety of our help documentation, which is included in the product.

Is this an appropriate use of gettext - putting entire documents in po files as opposed to just labels and messages?

The format has been made all the more complicated because sometimes (for tooltips or "what's this" icons) only a small part of the help doc is needed, resulting in single phrases/paragraphs being entries in the po file, which are then concatenated together when the user views the help... making the actual act of translation challenging.

Is there a better way to internationalize end user help documentation?

Answer 1

I would probably not consider storing entire documents in your i18n files. As you've noted, these are better suited for small chunks of text that is normally hard coded into the application. Your help documents are more-or-less entities that can be stored else-where, perhaps in a database so it's easy to update them on the fly. Then you can load the document that corresponds to the user's language settings. This way they can be maintained independently of your application and by non-developers. Another advantage of externalizing the documents is so that you can generate other forms of end-user documentation with out resorting to parsing your i18n files.

Answer 2

I would be inclined to say that gettext is a decent tool for the job, if you do it right. Doing it right means splitting the document to bite-sized chunks, usually paragraphs. See how po4a works. That way the translators only re-translate those parts of the document that have changed.

Generally keeping translated documents up-to-date is quite a bit of work however you do it. I have not heard about any method significantly better than po4a and using one translation system for all your needs has some benefits of your own.