Translating the Manual

This chapter deals with translating the PHP-GTK 2 documentation. Translating the documentation is the process of taking the previously written English documentation and rewritting it in another language.

Getting Started

Congratulations! By reading this tutorial, you are already on your way to translating the documentation. Reading this tutorial (the whole "PHP-GTK 2 Documentation" tutorial, not just this section) is the first step in getting involved in the translation efforts. Throughout this section of the tutorial, anytime that you see lang you should replace it with the two (or four in some cases) letter abbreviation for the language you are planning to translate the documentation into.

Once you have finished reading this tutorial, there are a few files that need to be translated so that the docs can be built properly and there start of the docs for your language are available:

  • manual/lang/preface.xml
  • manual/lang/bookinfo.xml
  • manual/lang/language-defs.ent
  • stylesheets/common/lang.xml
These four files provide the basics for the documentation as well as a list of commonly used words and phrases.

Once these files have been translated they should be emailed to the php-gtk-doc mailing list. A member of the documentation team will check the files to make sure that they work properly with the build system. The doc team will check your files and let you know if everything is OK as quickly as they can.

When sending the files to the mailing list, rename language-defs.ent to language-defs.ent.txt. This will prevent the mailing list server from dropping the file.

Translating Files

Once the four base files have been translated the next step is to translate other files to provide some content for the new language version. Before a new language version is made available, there must be enough content for anyone who wishes to read the new version. Therefore, a translated version will not be made available until there are at least three tutorials translated. A good place to start is this tutorial.

If three tutorials are already translated, feel free to translate any other file in the docs.

Submitting Translated Files

The documentation source is controlled with CVS. While anyone may checkout the docs, not everyone may commit changes. Before one is given permissions to commit files directly, they must undergo a bit of a probationary period. During this period, all translated files should be mailed to the php-gtk-doc mailing list. A member of the doc team will review your changes and commit the files to CVS on your behalf. After a few rounds of emailing changes, the doc team will petition the powers that be to grant you the permission needed to commit the files on your own.