6. Translating a document

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. Optional but recommended: drop the document to translation. Run: 

    $ publican trans_drop

    Publican creates a new subdirectory, named trans_drop/. The trans_drop/ subdirectory contains a snapshot of the source files of the document. When the trans_drop/ directory is present in a documentation project, Publican uses its content as the basis for the commands documented later in this procedure.

  3. 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.

  4. 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 F, 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, plus a Revision_History.xml file that tracks the history of this particular translation. When created for the first time, the Revision_History.xml file records the date on which the PO files for this translation were created, and the version of the source language XML (taken from the source language's Revision_History.xml file) on which this translation is therefore based.

    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, and adds a new entry to the translation's Revision_History.xml file to record the date on which the PO files for this translation were refreshed, and the version of the source language XML on which the revision is based. 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.

  5. Translate the strings contained in the PO files.

  6. If you are updating a previously published translation of this revision in the source language, use Publican's publican add_revision command to describe your changes or corrections. Publican updates the Revision_History.xml file for you.

    If the document has changed in its original language, use the publican trans_drop, publican update_pot, and publican update_po commands as described earlier in this procedure instead.

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

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.

6.2. Translating Indexes and Glossaries

DocBook automatically collates and sorts <glossentry> elements into a book's glossary; and <primary>, <secondary>, and <tertiary> <indexterm> elements into a book's index. Entries are sorted automatically, and although this system works well for languages written with an alphabet, abugida, or syllabic script, languages written with logograms sort less well.

To manually adjust the sort order of a glossary entry or index entry, manually add DocBook's sortas attribute to the XML element. For example, to ensure that the Japanese word 暗号化 sorts correctly in an index, specify: 

#. Tag: indexterm
#, no-c-format
msgid "<primary>encryption</primary>"
msgstr "<primary sortas="あんごうか">暗号化</primary>"

Similarly, to ensure that the Japanese word 暗号化 sorts correctly in a glossary, specify: 

#. Tag: glossentry
#, no-c-format
msgid "<glossterm>encryption</glossterm>"
msgstr "<glossterm sortas="あんごうか">暗号化</glossterm>"