L10N/how to build a translated book from translated files on Zanata

Click here to set up this language box

Getting the Original Folders and Files

Normally, you can create a book with publican using the publican create command. This command creates a directory structure which is described in the publican manual. Here is this structure:

• publican.cfg
• en-US (directory)
  • Test_Book.xml
  • Test_Book.ent
  • Revision_History.xml
  • Preface.xml
  • Chapter.xml
  • Book_Info.xml
  • Author_Group.xml
  • images (directory)
    • icon.sv

The Chapter.xml file is a template for creating chapter files. Chapter files contain the content that make up a book.

In our situation, we do not need to create the book as it has already been created by the author. In fact, we can get the above directory structure, including the chapters that have been added by the author from the [git.fedorahosted.org] site.

Once in this site, find your guide and click its name on the left side the screen. Then in the guide's page, choose the branch (generally the newer one) that you have translated. In the branch's page, click on the line corresponding to the last commit. The new displayed page should look like the following:

In the download section, click on one of the downloadable archives to download it.

Extract the content in any folder you want.

Preparing the translation files

• Open a terminal and change to the root directory of the guide. The one that contains the directory structure presented above.
• As a standard user, use the following command:

$ publican trans_drop

With this command, 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.

• Generate portable object template (POT) files from the XML files, using the following command:

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

• Generate portable object (PO) files from the POT files to begin translation into a particular language:

$ publican update_po --langs=language_code

At this stage, you could receive warnings such as "DEBUG: Publican: Configuration loaded. firstname is a mandatory argument at /usr/bin/publican line 1194. This mean that your configuration of Publican is not completed – see the Configuration of Publican section above. If necessary correct it and reuse the command.

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.

Replace the .po files in the <language-code> directory with the translated ones =

• Go to the Zanata, log in, and open your project/branch/language page. Select your language and download the po files using the Downlad All (zip) link shown in the following picture:

• Extract the archive
• Copy/paste the po files from the archive to replace the original ones.

Your are now ready to build your translated book.

Building the Translated Book

To build the book use the following command:

$ publican build --formats=html,pdf --langs=fr

Of course, replace the language code (here fr) with your one and add – or remove – formats you want.

Normally if everything goes well – but it is probably a bit far from this —, the resulting books should be placed in a tmp subdirectory.

Troubleshooting

Fuzzy Messages

If you plan to have a book to see the messages in context in order to approve them, you may still have some fuzzy messages. Unfortunately, this crashes the building. Fortunately, Publican gives information about where the trouble occurred, e.g.:

	Fusionner fr/After_Installation.po >> trans_drop/After_Installation.xml -> tmp/fr/xml_tmp//After_Installation.xml
AVERTISSEMENT : message approximatif dans le fichier PO.
45: "Both of these tools will allow you to configure user-specific s...

Here the message is in French and it means: WARNING: Fuzzy message in the po file.

In such case, edit the po file and remove all the #fuzzy lines you find in After_Installation.po. Save your file and reuse the building command again.

Bad XML source files

In some cases, you may get this kind of message:

DTD Validation failed for '/home/jaaf/Documents/install-guide-625e08c186c09c1abce89f3f0bf37c37563c7880/tmp/fr/xml/Installation_Guide.xml': 
Booting_the_Installation.xml:105: validity error : Element keycombo content does not follow the DTD, expecting (keycap | keycombo | keysym | mousebutton)+, got (keycap CDATA keycap)

Normally it should not happen but life is different. In this case, correct the fault as you can. For example, just removed the troublesome <keycombo> tag.