No edit summary |
|||
(25 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
After a guide has been translated on Zanata, the language team has to make a thorough review of all the messages in order to correct and finally approve them. Zanata is a tremendous tool both for translating and reviewing, nevertheless, it is sometime difficult to deal with some aspects such as punctuation, verb tenses, and so on, without viewing both the original and the translated messages in context. Depending on whether the message is an image caption, or a list item, or the content of a message box,or includes a internal link (section, chapter, figure,…) as part of the sentence itself, translation may vary a bit? | After a guide has been translated on Zanata, the language team has to make a thorough review of all the messages in order to correct and finally approve them. Zanata is a tremendous tool both for translating and reviewing, nevertheless, it is sometime difficult to deal with some aspects such as punctuation, verb tenses, and so on, without viewing both the original and the translated messages in context. Depending on whether the message is an image caption, or a list item, or the content of a message box,or includes a internal link (section, chapter, figure,…) as part of the sentence itself, translation may vary a bit? | ||
Moreover, the presence of numerous tags, sometimes nested, make the visual aspect a bit far from the rendered text, and thus doesn't facilitate detection of erroneous punctuation or spacing. | |||
All this is why, having the guide in the form of a translated finalized book may be a precious help for reviewers. This page explains how to build it. | |||
{{admon/warning|This page doesn't explain how to create a book from scratch. It is only a kind of shortcut for translation teams to quickly have a preview of their work before the final proofreading and approval of messages. To learn how to create a book from scratch, please refer to the Publican manual available in the Publican-doc package.}} | |||
==Installing Publican == | ==Installing Publican == | ||
The tools used to build the Fedora Guides is Publican. Install it with: | The tools used to build the Fedora Guides is Publican. Install it with: | ||
<pre>su -c 'dnf install publican-doc publican- | <pre>su -c 'dnf install publican publican-doc publican-fedora'</pre> | ||
{{admon/tip|Don't spare the installation of publican-doc. It will be a very valuable asset for troubleshooting. The files are in ''/usr/share/doc/publican''.}} | {{admon/tip|Don't spare the installation of ''publican-doc''. It will be a very valuable asset for troubleshooting. The files are in ''/usr/share/doc/publican-doc''.}} | ||
{{admon/tip|Don't spare the installation of ''publican-fedora''. It provides necessary models to build project ''"brand: fedora"'' in ''publican.cfg''.}} | |||
<span id="config"></span> | |||
==Configuring Publican == | ==Configuring Publican == | ||
Before using Publican, you should at least set the user's defaults which are:firstname, surname, email, formats, lang, langs. Please refer to the relevant page the Publican User's Gude in ''/usr/share/doc/publican-doc/en-US/index.html''. | Before using Publican, you should at least set the user's defaults which are: firstname, surname, email, formats, lang, langs. Please refer to the relevant page the Publican User's Gude in ''/usr/share/doc/publican-doc/en-US/index.html'' (Chapter 2.). | ||
Normally using the three commands that follow should be enough for the needs of this tutorial: | |||
<pre> | |||
echo 'firstname: "André"' >>~/.publican.cfg | |||
echo 'surname: "Dupneu"' >>~/.publican.cfg | |||
echo 'email: "chefducontentieux@dupneu.com"' >>~/.publican.cfg | |||
</pre> | |||
Of course, replace the personal data with you own. | |||
==Getting the Original Folders and Files== | ==Getting the Original Folders and Files== | ||
Line 32: | Line 49: | ||
The Chapter.xml file is a template for creating chapter files. Chapter files contain the content that make up a book. | 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 [[https:// | 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 [[https://https://pagure.io/ https://pagure.io/]] site. | ||
Change to the directory where you want to download the files. Then run: | |||
git clone -b {{Replace|BRANCH}} https://pagure.io/{{Replace|PROJECT_NAME}} | |||
where {{Replace|BRANCH}} is the name of the project branch and {{Replace|PROJECT_NAME}} the name of the project. | |||
For example to get the release-notes files for F24, run: | |||
git clone -b f24 https://pagure.io/release-notes | |||
{{admon/warning|Be aware that the branch name is case sensitive, thus it is advisable to go on the site and check the branch and the project names.}} | |||
== Building the Original Guide (occasional situation) == | |||
It may happen that a book, proposed for translation on Zanata is not yet available on the docs.fedoraproject.org site. As such a guide is also of great help for translators during the translation process, one may want to build it. To do so, use the following command : | |||
<pre> | |||
$ publican build --formats=html,html-single,pdf --langs=en-US | |||
</pre> | |||
{{admon/warning|At this stage, you could receive errors such as "Failed to load brand : /usr/share/publican/Common_Content/fedora/publican.cfg at /usr/bin/publican line 1004.". You may install if from publican-* with ''dnf'' or change "brand: common" in ''publican.cfg''}} | |||
==Preparing the translation files == | ==Preparing the translation files == | ||
Line 65: | Line 93: | ||
{{admon/warning|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 [[#config|Configuration of Publican]] section above. If necessary correct it and reuse the command.}} | {{admon/warning|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 [[#config|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 == | == Replace the .po files in the <language-code> directory with the translated ones == | ||
Line 86: | Line 114: | ||
Of course, replace the language code (here fr) with your one and add – or remove – formats you want. | Of course, replace the language code (here fr) with your one and add – or remove – formats you want. | ||
Normally if everything goes well – but | Normally if everything goes well – but real life is not that easy —, the resulting books should be placed in a '''tmp''' subdirectory. | ||
==Troubleshooting == | ==Troubleshooting == | ||
===Fuzzy Messages=== | ===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. | 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 let in the po files. | ||
Unfortunately, this | Unfortunately, this makes the build process crash. Fortunately, ''Publican'' gives information about where the trouble occurred, e.g.: | ||
<pre> Fusionner fr/After_Installation.po >> trans_drop/After_Installation.xml -> tmp/fr/xml_tmp//After_Installation.xml | <pre> Fusionner fr/After_Installation.po >> trans_drop/After_Installation.xml -> tmp/fr/xml_tmp//After_Installation.xml | ||
Line 101: | Line 129: | ||
Here the message is in French and it means: WARNING: Fuzzy message in the po file. | 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 | In such case, edit the po file and remove all the '''#fuzzy''' lines you find in ''After_Installation.po''. Save your file and use the building command again. | ||
If you don't plan to publish content online, another solution is to add '''--showfuzzy''' in you build command. | |||
===Bad XML source files === | ===Bad XML source files === | ||
Line 111: | Line 141: | ||
Normally it should not happen but life is different. In this case, correct the fault as you can. For example, just remove the troublesome <keycombo> tag. | Normally it should not happen but life is different. In this case, correct the fault as you can. For example, just remove the troublesome <keycombo> tag. | ||
After that, | Note : Even if Pelican tell you to look in ''Booting_the_Installation.'''xml''''', you'll probably have to fix your error in ''Booting_the_Installation.'''po'''''. | ||
After that, ''if'' you had to change the xml files, you should rerun the '''update_pot''' and '''update_po''' commands above. Then rerun the | |||
'''build''' command. | |||
===mismatched tag === | |||
In some cases, you may get this kind of message: | |||
<pre>mismatched tag at line 6, column 185, byte 422: | |||
%BOOK_ENTITIES; | |||
]> | |||
<para>Une partition étendue peut contenir plusieurs partitions (maintenant appelées <firstterm>partitions logiques</firstterm> par opposition aux quatre firstterm>partitions primaires</firstterm> vues précédemment). Chacune de ces partitions logique est précédée d'un secteur (appelé Extended Boot Record (<acronym>EBR</acronym>) utilisé à la manière d'un MBR, à la différence que deux entrées de partition seulement sont utilisées. l'une qui pointe sur la partition logique elle-même, l'autre qui pointe sur l'EBR de la partition logique suivante. Les partitions sont ainsi chaînées et leur nombre n'est plus limité que par la capacité du disque lui-même et par l'étendue adressable. </para> | |||
========================================================================================================================================================================================^ | |||
</pre> | |||
In this case, one '''<''' is missing from string, correct the fault. | |||
<hr/> | |||
===Some characters are rendered by a # in the pdf file === | |||
Some times, it appears that some characters are not correctly rendered in the pdf but are replaced with a #. It is probably due to the fact that the builder cannot find a fallback font that provides the wrongly rendered character. For example, with the French language, the narrow-no-break space normally necessary before a high punctuation (; ! ? ) was rendered by a #. Just adding the following lines at the end of {{Path|/usr/share/publican/xsl/pdf.xsl}} solved the trouble: | |||
<pre> | |||
<xsl:param name="title.font.family"> | |||
<xsl:text>FreeSans,Liberation Sans,sans-serif</xsl:text> | |||
</xsl:param> | |||
<xsl:param name="body.font.family"> | |||
<xsl:text>FreeSans,Liberation Sans,sans-serif</xsl:text> | |||
</xsl:param> | |||
<xsl:param name="monospace.font.family"> | |||
<xsl:text>Liberation Mono,monospace</xsl:text> | |||
</xsl:param> | |||
<xsl:param name="sans.font.family"> | |||
<xsl:text>FreeSans,Liberation Sans,sans-serif</xsl:text> | |||
</xsl:param> | |||
</pre> | |||
For more information, please refer to https://bugzilla.redhat.com/show_bug.cgi?id=1344078 | |||
===No images in the pdf file === | |||
After having built you pdf with publican, from the root directory of the document, please run the following commands: | |||
cd tmp/{{Replace|language code}}/xml | |||
cp /usr/share/publican/fop/fop.xconf ./ | |||
fop -c fop.xconf -fo {{Replace|document name}}.fo -pdf ../pdf/{{Replace|document name}}.pdf | |||
For more information, please see https://bugzilla.redhat.com/show_bug.cgi?id=1290423 | |||
[[Category:Localization]] |
Latest revision as of 04:55, 15 June 2016
After a guide has been translated on Zanata, the language team has to make a thorough review of all the messages in order to correct and finally approve them. Zanata is a tremendous tool both for translating and reviewing, nevertheless, it is sometime difficult to deal with some aspects such as punctuation, verb tenses, and so on, without viewing both the original and the translated messages in context. Depending on whether the message is an image caption, or a list item, or the content of a message box,or includes a internal link (section, chapter, figure,…) as part of the sentence itself, translation may vary a bit?
Moreover, the presence of numerous tags, sometimes nested, make the visual aspect a bit far from the rendered text, and thus doesn't facilitate detection of erroneous punctuation or spacing.
All this is why, having the guide in the form of a translated finalized book may be a precious help for reviewers. This page explains how to build it.
Installing Publican
The tools used to build the Fedora Guides is Publican. Install it with:
su -c 'dnf install publican publican-doc publican-fedora'
Configuring Publican
Before using Publican, you should at least set the user's defaults which are: firstname, surname, email, formats, lang, langs. Please refer to the relevant page the Publican User's Gude in /usr/share/doc/publican-doc/en-US/index.html (Chapter 2.).
Normally using the three commands that follow should be enough for the needs of this tutorial:
echo 'firstname: "André"' >>~/.publican.cfg echo 'surname: "Dupneu"' >>~/.publican.cfg echo 'email: "chefducontentieux@dupneu.com"' >>~/.publican.cfg
Of course, replace the personal data with you own.
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 [https://pagure.io/] site.
Change to the directory where you want to download the files. Then run:
git clone -b <BRANCH> https://pagure.io/<PROJECT_NAME>
where <BRANCH> is the name of the project branch and <PROJECT_NAME> the name of the project.
For example to get the release-notes files for F24, run:
git clone -b f24 https://pagure.io/release-notes
Building the Original Guide (occasional situation)
It may happen that a book, proposed for translation on Zanata is not yet available on the docs.fedoraproject.org site. As such a guide is also of great help for translators during the translation process, one may want to build it. To do so, use the following command :
$ publican build --formats=html,html-single,pdf --langs=en-US
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
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:
![](/w/uploads/thumb/2/25/Zanata-download-po.png/300px-Zanata-download-po.png)
- 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 real life is not that easy —, 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 let in the po files. Unfortunately, this makes the build process crash. 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 use the building command again.
If you don't plan to publish content online, another solution is to add --showfuzzy in you build command.
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 remove the troublesome <keycombo> tag.
Note : Even if Pelican tell you to look in Booting_the_Installation.xml, you'll probably have to fix your error in Booting_the_Installation.po.
After that, if you had to change the xml files, you should rerun the update_pot and update_po commands above. Then rerun the build command.
mismatched tag
In some cases, you may get this kind of message:
mismatched tag at line 6, column 185, byte 422: %BOOK_ENTITIES; ]> <para>Une partition étendue peut contenir plusieurs partitions (maintenant appelées <firstterm>partitions logiques</firstterm> par opposition aux quatre firstterm>partitions primaires</firstterm> vues précédemment). Chacune de ces partitions logique est précédée d'un secteur (appelé Extended Boot Record (<acronym>EBR</acronym>) utilisé à la manière d'un MBR, à la différence que deux entrées de partition seulement sont utilisées. l'une qui pointe sur la partition logique elle-même, l'autre qui pointe sur l'EBR de la partition logique suivante. Les partitions sont ainsi chaînées et leur nombre n'est plus limité que par la capacité du disque lui-même et par l'étendue adressable. </para> ========================================================================================================================================================================================^
In this case, one < is missing from string, correct the fault.
Some characters are rendered by a # in the pdf file
Some times, it appears that some characters are not correctly rendered in the pdf but are replaced with a #. It is probably due to the fact that the builder cannot find a fallback font that provides the wrongly rendered character. For example, with the French language, the narrow-no-break space normally necessary before a high punctuation (; ! ? ) was rendered by a #. Just adding the following lines at the end of /usr/share/publican/xsl/pdf.xsl solved the trouble:
<xsl:param name="title.font.family"> <xsl:text>FreeSans,Liberation Sans,sans-serif</xsl:text> </xsl:param> <xsl:param name="body.font.family"> <xsl:text>FreeSans,Liberation Sans,sans-serif</xsl:text> </xsl:param> <xsl:param name="monospace.font.family"> <xsl:text>Liberation Mono,monospace</xsl:text> </xsl:param> <xsl:param name="sans.font.family"> <xsl:text>FreeSans,Liberation Sans,sans-serif</xsl:text> </xsl:param>
For more information, please refer to https://bugzilla.redhat.com/show_bug.cgi?id=1344078
No images in the pdf file
After having built you pdf with publican, from the root directory of the document, please run the following commands:
cd tmp/<language code>/xml
cp /usr/share/publican/fop/fop.xconf ./
fop -c fop.xconf -fo <document name>.fo -pdf ../pdf/<document name>.pdf
For more information, please see https://bugzilla.redhat.com/show_bug.cgi?id=1290423