[documentation-guide] Moved Translations instructions from Fedora Wiki to Translations chapter
Petr Kovář
pmkovar at fedoraproject.org
Thu Sep 15 19:47:41 UTC 2011
commit f713a740fc6c877f1161c490182cdfe2271c9be9
Author: Petr Kovar <pkovar at redhat.com>
Date: Thu Sep 15 21:44:43 2011 +0200
Moved Translations instructions from Fedora Wiki to Translations chapter
en-US/translations.xml | 198 ++++++++++++++++++++++++++++++++++++++++++++---
1 files changed, 185 insertions(+), 13 deletions(-)
---
diff --git a/en-US/translations.xml b/en-US/translations.xml
index 4865bc8..e71ceea 100644
--- a/en-US/translations.xml
+++ b/en-US/translations.xml
@@ -5,18 +5,190 @@
]>
<chapter id="chap-documentation_guide-translations">
<title>Translations</title>
- <para>Translations are an important piece of the documentation process. If users can't read the native language that the documentation is written in then the documentation isn't helpful to that user and the hard work that went into the documentation isn't being utilized to its fullest extent.</para>
- <para>The Fedora Documentation Team utilizes the <ulink url="https://www.transifex.net">Transifex</ulink> platform for providing pot files to translators and receiving po files for publishing onto the <ulink url="https://docs.fedoraproject.org">Fedora Documentation website</ulink>.</para>
- <section id="sect-documentation_guide-translations-tools">
- <title>Tools for working with Transifex</title>
- <para></para>
- <section id="sect-documentation_guide-translations-tools-installing">
- <title>Installing the Transifex tools</title>
- <para><screen><command>sudo yum install tx</command></screen></para>
- </section>
- <section id="sect-documentation_guide-translations-tools-using">
- <title>Setting up and Using TX</title>
- <para>Setting up and using TX is best explained at <ulink url="https://fedoraproject.org/wiki/Setting_up_a_document_with_Transifex" />.</para>
- </section>
+ <para>Translations are an important piece of the documentation process. If users cannot read the native language that the documentation is written in, then the documentation is not helpful to those users and the hard work that went into the documentation is not being utilized to its fullest extent.</para>
+ <para>
+ This chapter discusses how translations are provided in Fedora
+ documentation.
+ </para>
+ <section id="sect-documentation_guide-translations-translating-documentation">
+ <title>Translating Documentation</title>
+ <para>
+ The cornerstone of translation when using XML files such as
+ DocBook is the <firstterm>Portable Object</firstterm> or
+ <acronym>PO</acronym> file. PO files provide a way for
+ independent individuals or teams to translate documents.
+ </para>
+ <para>
+ PO files are usually found in two forms:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ the <filename class="extension">.pot</filename> file, or
+ <firstterm>PO Template</firstterm> (<acronym>POT</acronym>)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ the <filename class="extension">.po</filename> file, or
+ translation file (<acronym>PO</acronym>)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ A POT is, as the name suggests, a blank template for new
+ translations. It contains some header information and a list of
+ strings based on the content of the original XML file from which
+ it was created. Translators do not alter the POT. The POT
+ should only be changed after changes are made to the original
+ XML file from which it is derived.
+ </para>
+ <para>
+ PO strings fall into three categories:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <firstterm>translated</firstterm>, meaning the string has
+ been handled by a translator and its source has not changed
+ since then
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <firstterm>fuzzy</firstterm>, meaning the string has changed
+ since it was last handled by a translator
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <firstterm>untranslated</firstterm>, meaning no translation
+ has yet been provided for this string, or it is brand new
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section id="sect-documentation_guide-translations-introducing-transifex">
+ <title>Introducing Transifex.net</title>
+ <para>The Fedora Project uses Transifex, an open source translation platform, to power the translation of software and documentation. All translations are hosted at <ulink url="https://www.transifex.net/">Transifex.net</ulink>, which provides a web application allowing translators to write, submit, and manage their translations. Document translations are then pulled into the document's Git repository, where they can be built and published to <ulink url="https://docs.fedoraproject.org">Fedora Documentation website</ulink>.</para>
+<para>Documentation maintainers are responsible for the following:</para>
+<itemizedlist>
+<listitem><para>pushing changes to their guide or other document to Transifex.net</para></listitem>
+<listitem><para>pulling updated translations back to their git repository</para></listitem>
+<listitem><para>publishing the translations to <ulink url="https://docs.fedoraproject.org">http://docs.fedoraproject.org</ulink></para></listitem>
+</itemizedlist>
+<para>The following sections explain how to set up Transifex for use with your document.</para>
+</section>
+ <section id="sect-documentation_guide-translations-creating-account">
+ <title>Creating an Account on Transifex.net</title>
+<para>Go to <ulink url="https://www.transifex.net/">Transifex.net</ulink> and click on <guilabel>Register</guilabel> in the top right hand corner to create an account.</para>
+</section>
+ <section id="sect-documentation_guide-translations-installing-client">
+ <title>Installing the Transifex Client</title>
+<para>To use Transifex with your Git repository, you need the <package>transifex-client</package> package installed from the Fedora repositories.</para>
+</section>
+ <section id="sect-documentation_guide-translations-configuring-transifexrc">
+ <title>Configuring .transifexrc</title>
+<para>Edit the file <filename>~/.transifexrc</filename>, adding your Transifex.net username and password in the following format:</para>
+<screen>[https://www.transifex.net]
+hostname = https://www.transifex.net
+username = <replaceable>username</replaceable>
+password = <replaceable>password</replaceable>
+token =
+</screen>
+</section>
+ <section id="sect-documentation_guide-translations-initializing-transifex">
+ <title>Initializing Transifex in Your Git Repository</title>
+<para>Go to the Git repository of your document and change to the current Fedora release branch. Alternatively, you can create a new branch specifically for translations by branching the release branch, and then periodically merge updated content from the release branch to the branch with translations. After choosing the approach that is appropriate for you and changing to the branch, enter the following commands, replacing <code><replaceable>url</replaceable></code> with the URL of your document's project page on Transifex.net:</para>
+<screen>tx init
+</screen>
+<screen>tx set --auto-remote <replaceable>url</replaceable>
+</screen>
+<para>This will create a <code>.tx</code> folder in your repository.</para>
+<note>
+<title>I cannot find my document on Transifex.net!</title><para>Most Fedora documents already have a project page on Transifex.net, but if your document is new you may need to set one up. Ask on the Fedora Docs Project mailing list for help with how to do this.</para>
+</note>
+</section>
+ <section id="sect-documentation_guide-translations-mapping-language-codes">
+ <title>Mapping Language Codes</title>
+<para>If you have translation folders already in your repository, you may need to map the language codes to the ones used by Transifex.net, if they are different.</para>
+<para>To do this, open the file <filename>.tx/config</filename>. You should see a <code>[main]</code> section which allows you to set configurations for the whole document, followed by sections for the individual files of which your document is comprised (<emphasis>resources</emphasis>, in Transifex terminology). In the <code>[main]</code> section, edit the <code>lang_map</code> line to map the language codes in your repository to the ones used on Transifex.net. For example, if your repository uses <code>ro-RO</code> for Romanian and <code>bg-BG</code> for Bulgarian, but Transifex.net uses <code>ro</code> and <code>bg</code> respectively, the <code>lang_map</code> line should look like this:</para>
+<screen>lang_map = ro:ro-RO,bg:bg-BG
+</screen>
+<para>The language code used in Transifex.net comes first, followed by the language code used by the folder in your repository. Multiple language mappings are given as a comma-separated list.</para>
+<note>
+<title>Finding currently active Translation Teams</title><para>To find out what Translation Teams currently have translations for your document, and to see what language code they use, click on <guilabel>All Resources</guilabel> under <guilabel>Project Releases</guilabel> on your document's Transifex.net project page. This will bring up a list of all currently active Translation Teams, with the name of each language followed by its language code in parentheses. You can also see how much of your document each team has translated, and the details of the last submitted translation.</para>
+</note>
+<para>For your <code>.tx/config</code> file you can simply reuse the following language code mappings, which are utilized by a number of Fedora guides that are tracked by Transifex.net:</para>
+<screen>lang_map = aln:aln-AL, ar:ar-SA, as:as-IN, bal:bal-PK, bg:bg-BG,
+bn:bn-BD, bn_IN:bn-IN, bs_BA:bs-BA, ca:ca-ES, cs:cs-CZ, da:da-DK,
+de_CH:de-CH, de:de-DE, el:el-GR, en_GB:en-GB, es:es-ES, fa:fa-IR, fi:fi-FI,
+fr:fr-FR, gu:gu-IN, he:he-IL, hi:hi-IN, hr:hr-HR, hu:hu-HU, id:id-ID,
+is:is-IS, it:it-IT, ja:ja-JP, kn:kn-IN, ko:ko-KR, lt:lt-LT, mai:mai-IN,
+ml:ml-IN, mr:mr-IN, ms:ms-MY, nb:nb-NO, nds:nds-DE, nl:nl-NL, nn:nn-NO,
+or:or-IN, pa:pa-IN, pl:pl-PL, pt_BR:pt-BR, pt:pt-PT, ro:ro-RO, ru:ru-RU,
+si:si-LK, sk:sk-SK, sl:sl-SI, sq:sq-AL, sr:sr-RS, sr at latin:sr-Latn-RS,
+sv:sv-SE, ta:ta-IN, te:te-IN, tr:tr-TR, uk:uk-UA, ur:ur-PK, vi:vi-VN,
+zh_CN:zh-CN, zh_HK:zh-HK, zh_TW:zh-TW</screen>
+</section>
+ <section id="sect-documentation_guide-translations-editing-file-filters">
+ <title>Editing File Filters</title>
+<para>By default, <application>transifex-client</application> downloads translations and stores them in a <filename>translations</filename> folder in your repository. For Fedora documentation, <application>transifex-client</application> must be configured to download the translations to the root folder of your repository, with each language having its own folder, so that Publican can find them.</para>
+<para>For each resource listed in the <filename>.tx/config</filename> file, edit the <code>file_filter</code> line to give the correct location:</para>
+<screen>file_filter = <replaceable>lang</replaceable>/<replaceable>resource</replaceable>.po
+</screen>
+<para>Replace <replaceable>resource</replaceable> with the name of the resource, which is the second part of the section title shown directly above. For example:</para>
+<screen>[fedora-release-notes.Amateur_Radio]
+file_filter = <replaceable>lang</replaceable>/Amateur_Radio.po
+source_file = pot/Amateur_Radio.pot
+source_lang = en
+</screen>
+<para>Congratulations, your document repository is now configured for Transifex!</para>
+</section>
+ <section id="sect-documentation_guide-translations-updating-pot-files">
+ <title>Updating POT Files</title>
+<para>Run the following command to update all POT files in your document's repository:</para>
+<screen>publican update_pot
+</screen>
+<para>After running the command, you can proceed with pushing transitions to Transifex.net. Refer to <xref linkend="sect-documentation_guide-translations-pushing-pulling"/> for more information.</para>
+</section>
+ <section id="sect-documentation_guide-translations-pushing-pulling">
+ <title>Pushing and Pulling Translations</title>
+<para>Whenever a change is made to your document, run the <command>publican update_pot</command> command. After that, run the following command to push the changes to Transifex.net so that translators can translate them:</para>
+<screen>tx push -s
+</screen>
+<para>If you need to edit a <filename>.po</filename> file locally, you can push the changes back to Transifex.net:</para>
+<screen>tx push -t
+</screen>
+<para>To pull updated translations from Transifex.net:</para>
+<screen>tx pull -a
+</screen>
+<para>You can use the <option>-l</option> option to specify specific languages to pull, for example if you know that a particular language has new translations available.</para>
+<para>Refer to the Fedora Wiki page <ulink url="https://fedoraproject.org/wiki/Publishing_a_document_with_Publican">Publishing a document with Publican</ulink> for information on how to publish translated documentation to <ulink url="https://docs.fedoraproject.org">docs.fedoraproject.org</ulink>.</para>
+<important><title>Translation notifications</title><para>Make sure you select the <guilabel>Watch</guilabel> button on your document's Transifex.net project page to receive email notifications when new translations are available. The <guilabel>Watch</guilabel> button is located below the document's title.</para></important>
+</section>
+ <section id="sect-documentation_guide-translations-branching-updating">
+ <title>Branching and Updating Translations Before a New Release</title>
+<para>First, change to the branch intended for the previous Fedora release. Then create a new branch for the upcoming release and change to the branch:</para>
+<screen>git checkout -b <replaceable>newbranch</replaceable>
+</screen>
+<para>Assuming that the content development for the upcoming release happened in the master branch, which is different from the release branch, you should merge the updates from the master branch:</para>
+<screen>git merge master
+</screen>
+<para>After successful merging, check that the resource configuration in the <filename>.tx/config</filename> file is still up-to-date and applies to the current documentation. Especially pay attention to changed, moved or removed chapters in your document. If you need to remove an unused resource, run the following command:</para>
+<screen>tx delete -r <replaceable>documentation</replaceable>.<replaceable>resource</replaceable>
+</screen>
+<para>For example, if you want to remove the resource Amateur_Radio from the Fedora Release Notes, execute the following command:</para>
+<screen>tx delete -r fedora-release-notes.Amateur_Radio
+</screen>
+<important><title>Use the development version</title><para>As of September 2011, you need to have the development version of <code>transifex-client</code> installed to use the <code>tx delete</code> command. Refer to <ulink url="http://help.transifex.net/user-guide/client/devel.html#development-version">http://help.transifex.net/user-guide/client/devel.html#development-version</ulink> for instructions on how to get the development version.</para></important>
+<para>When you are done with all necessary changes, follow the usual procedure with updating POT files and pushing and pulling translations that is described in <xref linkend="sect-documentation_guide-translations-updating-pot-files"/> and <xref linkend="sect-documentation_guide-translations-pushing-pulling"/>.</para>
+</section>
+ <section id="sect-documentation_guide-translations-additional-resources">
+ <title>Additional Resources</title>
+ <para>Setting up and using Transifex.net is also explained on Fedora Wiki, at <ulink url="https://fedoraproject.org/wiki/Setting_up_a_document_with_Transifex" />.</para>
+<note><title>Getting more help</title><para>Transifex.net has its own comprehensive documentation for <application>transifex-client</application> at <ulink url="http://help.transifex.net/user-guide/client/index.html">http://help.transifex.net/user-guide/client/index.html</ulink>. You can also post questions to the Docs Project mailing list or ask in the <literal>#fedora-docs</literal> IRC channel if you get stuck. The L10N Guide has lots of useful information on using Transifex from a translator's perspective: <ulink url="https://fedoraproject.org/wiki/L10N/Guide">https://fedoraproject.org/wiki/L10N/Guide</ulink>.</para></note>
</section>
</chapter>
More information about the docs-commits
mailing list