Product SiteDocumentation Site

3.3. 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.
  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 D, 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 3.4, “Building a document” for more information on building a document, and Section 3.5, “Packaging a book” on packaging a document.