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?

2 Answers 2


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.

  • That does not solve the issue of keeping the documents in various languages up-to-date, which is the problem.
    – Jan Hudec
    Commented Jun 11, 2012 at 15:41
  • I interpreted the problem as keeping large document-sized blocks of text in what is essentially key-value text files was clunky. I could be wrong as I have never used gettext, but I have done this type of thing in Java and Flex, and it was slightly annoying. In either case, by externalizing the documents you can keep them up-to-date from a separate app, independent of the app they will be used in. After that, it's all about defining a business process to do it. I am assuming that externalization is possible, since the OP hasn't ruled it out. Depending on the requirements, this may not work.
    – Jeremy
    Commented Jun 11, 2012 at 15:48
  • The question asks about how to handle translations. And you didn't answer that.
    – Jan Hudec
    Commented Jun 11, 2012 at 17:32

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.