Translations by nairobie

The po4a (po for anything) project goal is to ease translations (and more interestingly, the maintenance of translations) using gettext tools on areas where they were not expected like documentation.

This document is organized as follow:

This introducing chapter explains the motivation of the project and its philosophy. You should read it first if you are in the process of evaluating po4a for your own translations.

This chapter is a sort of reference manual, trying to answer the users' questions and to give you a better understanding of the whole process. This introduces how to do things with po4a and serve as an introduction to the documentation of the specific tools.

HOWTO begin a new translation?

HOWTO change the translation back to a documentation file?

HOWTO update a po4a translation?

HOWTO convert a pre-existing translation to po4a?

HOWTO add extra text to translations (like translator's name)?

HOWTO do all this in one program invocation?

This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us maintaining and improving it. It may also help you understanding why it does not do what you expected, and how to solve your problems.

This chapter groups the Frequently Asked Questions. In fact, most of the questions for now could be formulated that way: "Why is it designed this way, and not that one?" If you think po4a isn't the right answer to documentation translation, you should consider reading this section. If it does not answer your question, please contact us on the E<lt>po4a-devel@lists.alioth.debian.orgE<gt> mailing list. We love feedback.

5 Specific notes about modules

Actually, this section is not really part of this document. Instead, it is placed in each module's documentation. This helps ensuring that the information is up to date by keeping the documentation and the code together.

6 Known bugs and feature requests

Quite a few already :(

Why should I use po4a? What it is good for?

I like the idea of open-source software, making it possible for everybody to access to software and to their source code. But being French, I'm well aware that the licensing is not the only restriction to the openness of software: non-translated free software is useless for non-English speakers, and we still have some work to make it available to really everybody out there.

The perception of this situation by the open-source actors did dramatically improve recently. We, as translators, won the first battle and convinced everybody of the translations' importance. But unfortunately, it was the easy part. Now, we have to do the job and actually translate all this stuff.

Actually, open-source software themselves benefit of a rather decent level of translation, thanks to the wonderful gettext tool suite. It is able to extract the strings to translate from the program, present a uniform format to translators, and then use the result of their works at run time to display translated messages to the user.

But the situation is rather different when it comes to documentation. Too often, the translated documentation is not visible enough (not distributed as a part of the program), only partial, or not up to date. This last situation is by far the worst possible one. Outdated translation can reveal worse than no translation at all to the users by describing old program behavior which are not in use anymore.

The problem to solve

Translating documentation is not very difficult in itself. Texts are far longer than the messages of the program and thus take longer to be achieved, but no technical skill is really needed to do so. The difficult part comes when you have to maintain your work. Detecting which parts did change and need to be updated is very difficult, error-prone and highly unpleasant. I guess that this explains why so much translated documentation out there are outdated.

The po4a answers

So, the whole point of po4a is to make the documentation translation I<maintainable>. The idea is to reuse the gettext methodology to this new field. Like in gettext, texts are extracted from their original locations in order to be presented in a uniform format to the translators. The classical gettext tools help them updating their works when a new release of the original comes out. But to the difference of the classical gettext model, the translations are then re-injected in the structure of the original document so that they can be processed and distributed just like the English version.

Thanks to this, discovering which parts of the document were changed and need an update becomes very easy. Another good point is that the tools will make almost all the work when the structure of the original document gets fundamentally reorganized and when some chapters are moved around, merged or split. By extracting the text to translate from the document structure, it also keeps you away from the text formatting complexity and reduces your chances to get a broken document (even if it does not completely prevent you to do so).

Please also see the L<FAQ> below in this document for a more complete list of the advantages and disadvantages of this approach.

Supported formats

Currently, this approach has been successfully implemented to several kinds of text formatting formats:

This is the Perl Online Documentation format. The language and extensions themselves are documented that way, as well as most of the existing Perl scripts. It makes easy to keep the documentation close to the actual code by embedding them both in the same file. It makes programmer life easier, but unfortunately, not the translator one.