4.6. Preparing a document for translation

Support for localization of documents was a key consideration in the design of Publican. The general translation workflow for documents developed in Publican is as follows:
  1. Complete the XML of a document.
    The XML for this version of the document should now be considered ‘frozen’. If your document is stored in a version-controlled repository, you should now move this version into a separate directory or branch. This allows writers to begin work on subsequent versions of the document in one branch, while providing a stable base for translation in another branch.
  2. Generate portable object template (POT) files from the XML files:
    $ publican update_pot
    If this is the first time that POT files have been created for this document, Publican creates a new subdirectory, named pot. The pot subdirectory holds a POT file for each XML file in the document. If Publican has created POT files for this document previously, Publican updates the existing POT files to reflect any changes in the XML since the POT files were last updated.

    Remove unused XML files

    Publican generates a POT file for every XML file in the XML directory, whether the XML file is used in the document or not. If you transform unused XML files into POT files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
    Use the $ publican print_unused command to generate a list of XML files that are not used in your document.
  3. Generate portable object (PO) files from the POT files to begin translation into a particular language:
    $ publican update_po --langs=language_code
    where language_code is the code for the target language. Refer to Appendix G, Language codes for more information about language codes. You can provide multiple language codes, separated by commas, to generate PO files for more than one language at a time. For example:
    $ publican update_po --langs=hi-IN,pt-BR,ru-RU,zh-CN
    If this is the first time that PO files have been created for a particular language, Publican creates a new subdirectory, named with the language code that you specified with the --langs= option. This subdirectory holds a PO file for each POT file in pot subdirectory. If Publican has created PO files for this language previously, Publican updates the existing PO files to reflect any changes in the POT files since the PO files were last updated. You can update existing PO files in every subdirectory with the --langs=all option:
    $ publican update_po --langs=all

    Remove unused POT files

    Publican generates a PO file for every POT file in the pot directory, whether the POT file is based on a corresponding XML file that is used in the document or not, or whether a corresponding XML file even exists. If you transform POT files for unused or deleted XML files into PO files, you waste the time and effort of volunteer translators, and waste money if you are paying for translations.
    When you generate PO files, Publican presents you with a warning for any POT files that do not have corresponding XML files, but will generate the PO file nevertheless. However, Publican will not warn you if a POT file exists for an XML file that is not used in the document.
  4. Translators translate the strings contained in the PO files.
  5. Build the document in the target language, for example:
    $ publican build --formats=html,html-single,pdf --langs=is-IS,nb-NO
    or package it in the target language, for example:
    $ publican package --lang=is-IS
    You can build the document in all languages for which you have translations with the --langs=all option, but note that you must package each language individually. Refer to Section 4.7, “Building a document” for more information on building a document, and Section 4.8, “Packaging a document” on packaging a document.

    Important — set Project-Id-Version for packaging

    The release number of RPM packages for translated documents is set by the Project-Id-Version parameter in the Article_Info.po or Book_Info.po file. For example, release 3 of a book in Japanese would have the following set at the start of the ja-JP/Book_Info.po file:
    "Project-Id-Version: 3\n"
    Note that the release number of a package in a particular language does not bear any relationship to the release number of the package for the same document in its original language or in any other language. The release number is specific to one particular language only.

4.6.1. Translation Author Group

Translation takes place after a book has been finalized. You do not need to know who will translate your book in order to give them credit. Create $translation/Author_Group.xml and add a valid DocBook authorgroup. The translator can add their details to this file and Publican will append it to $source_lang/Author_Group.xml when the book is build. This allows authors to finalize the original text without needing to know who will translate the book.