translation-quick-start-guide/en_US Translating_Documentation.xml, 1.3, 1.4
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Sun Oct 21 21:01:19 UTC 2007
Author: pfrields
Update of /cvs/docs/translation-quick-start-guide/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv20977
Modified Files:
Translating_Documentation.xml
Log Message:
Changes for style, readability, and translatability. A lot of these
changes I simply had to undo because they were making the text
unclear. The more we can adhere to the Style Guide and good standards
for technical documentation, the better.
I haven't looked at the other chapters yet.
Index: Translating_Documentation.xml
===================================================================
RCS file: /cvs/docs/translation-quick-start-guide/en_US/Translating_Documentation.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Translating_Documentation.xml 21 Oct 2007 19:10:00 -0000 1.3
+++ Translating_Documentation.xml 21 Oct 2007 21:01:17 -0000 1.4
@@ -10,81 +10,83 @@
]>
- <section id="sn_translating_docs">
+ <section id="sn_translating_docs">
<title>Translating Documentation</title>
<para>
- Once you have a Fedora Account and have become a member of the group 'cvsl10n', you'll be able to contribute translations to Docs (see Accounts and Subscriptions Chapter for detail).
+ To translate Fedora documentation, become a member of the
+ <systemitem>cvsl10n</systemitem> group. For more information on
+ account and subscriptions, refer to <xref linkend="sn_accounts"/>.
</para>
<para>
To translate documentation, you need a &FC; &FCMINVER; or later system with the following packages installed:
</para>
<itemizedlist>
<listitem>
- <para><package>gnome-doc-utils // Provdies xml2po</package></para>
+ <para><package>gnome-doc-utils</package></para>
</listitem>
<listitem>
- <para><package>xmlto //For testing build</package></para>
+ <para><package>xmlto</package></para>
</listitem>
<listitem>
- <para><package>make //For testing build</package></para>
+ <para><package>make</package></para>
</listitem>
</itemizedlist>
+ <para>The <package>gnome-doc-utils</package> package provides the
+ <command>xml2po</command> command, and does not require you to
+ install the GNOME desktop environment. The <package>xmlto</package>
+ and <package>make</package> packages contain tools necessary for
+ testing document builds and translations.</para>
<para>
To install these packages, use the following command:
</para>
-<screen>
-<command>su -c 'yum install gnome-doc-utils xmlto make'</command>
-</screen>
+ <screen><command><![CDATA[su -c 'yum install gnome-doc-utils xmlto make']]></command></screen>
+
+ <!-- You might be wondering, why all the <![CDATA[...]]> stuff? Well,
+ this is XML language for "verbatim content," or in this case, "things
+ that should not be translated." If we mark all command material with
+ CDATA containers, it cuts down on the number of strings translators
+ need to pay attention to. If you have a <replaceable> element in a
+ command, just leave it outside the container(s). -->
<section id="sn-get-started">
- <title>Get Started</title>
+ <title>Getting Started</title>
- <para>
- The Fedora documentation is stored in a CVS repository
- under the directory <filename>docs/</filename>. To list the available modules, run the following commands:
- </para>
+ <para>
+ The Fedora documentation is stored in a CVS repository under the
+ directory <filename>docs/</filename>. To list the available
+ modules, run the following commands:
+ </para>
-<screen>
-<command>export
-CVSROOT=:ext:<replaceable>username</replaceable>@cvs.fedoraproject.org:/cvs/docs</command>
-<command>cvs co -c</command>
-</screen>
+ <screen><command><![CDATA[export CVSROOT=:ext:]]><replaceable>username</replaceable><![CDATA[@cvs.fedoraproject.org:/cvs/docs]]></command>
+<command><![CDATA[cvs co -c]]></command></screen>
- <para>
- To download a module to translate, list the current modules in the repository and then check out that module. You must also check out the <filename>docs-common</filename> module to work
- with some modules.
- </para>
+ <para>
+ To download a module to translate, list the current modules in the
+ repository and then check out that module. You must also check
+ out the <filename>docs-common</filename> module to work with some
+ modules.
+ </para>
-<screen>
-<command>cvs co release-notes/</command>
-</screen>
+ <screen>
+ <command>cvs co release-notes/</command>
+ </screen>
- <para>
- Each release of &DISTRO; has their own subdirectory underneath.
- </para>
-<screen>
-<command>ls release-notes/</command>
-<command>CVS F-7 FC-5 FC-6 FC3 FC4 devel</command>
-</screen>
- <para>
- Each subdirectory of &DISTRO; contains a set of it's release. And usually translator works on devel/ subdirectory for future release.
- </para>
-<screen>
-<command>ls release-notes/devel/</command>
-<command>
- CVS css indexhtml-foot readmes.xsl
- Makefile en_US indexhtml-head scripts
- README-Accessibility fedora-release-notes.spec messages.mo xmlbeats
- README.fedora-release figs po</command>
-</screen>
- <para>
- Under po/ directory the above, .po files to be translated are stored. If you can not find your language .po file, then the .po file can be newly created from .pot file. Please remember that the newly created file must be added in cvs (cvs add) and then commited (cvs commit). Also you should check po/LINGUAS file if it contains your language code.
- </para>
- <para>
- To translate the document, simply get your language .po file and work just like Software translation, such as with Kbabel or gtranslator.
- </para>
+ <para>
+ Some modules are <firstterm>release specific</firstterm>, meaning
+ that they have a <firstterm>branch</firstterm>, or subdirectory,
+ for each release of &DISTRO;:
+ </para>
+ <screen><userinput><![CDATA[ls release-notes/]]></userinput>
+<computeroutput><![CDATA[CVS F-7 FC-5 FC-6 FC3 FC4 devel]]></computeroutput></screen>
+
+ <para>
+ The <filename class="directory">devel/</filename> branch is used
+ for the <emphasis>upcoming</emphasis> release of &DISTRO;. Often
+ translators work on this branch, and port changes back to previous
+ branches as required.
+ </para>
</section>
<section id="sn-creating-common">
@@ -97,6 +99,13 @@
class="directory">docs-common/common/</filename>.
</para>
+ <note>
+ <title>Example Locale is <replaceable>pt_BR</replaceable></title>
+ <para>The following examples use the locale code
+ <replaceable>pt_BR</replaceable>. Substitute your locale code
+ in these commands as necessary.</para>
+ </note>
+
<procedure>
<step>
<para>
@@ -109,13 +118,13 @@
<step>
<para>
Once you have created common entities for your locale and
- committed the results to CVS, create a locale file for the
- legal notice:
+ committed the results to CVS, create locale files for the
+ legal notices:
</para>
-<screen>
-<command>cd docs-common/common/</command>
-<command>cp legalnotice-opl-en_US.xml legalnotice-opl-<replaceable>pt_BR</replaceable>.xml</command>
+ <screen><command><![CDATA[cd docs-common/common/]]></command>
+<command><![CDATA[cp legalnotice-opl-en_US.xml legalnotice-opl-]]><replaceable>pt_BR</replaceable><![CDATA[.xml]]></command>
+<command><![CDATA[cp legalnotice-relnotes-en_US.xml legalnotice-relnotes-]]><replaceable>pt_BR</replaceable><![CDATA[.xml]]></command>
</screen>
<important>
@@ -128,13 +137,11 @@
</step>
<step>
<para>
- Then commit that file to CVS also:
+ Then commit those file to CVS also:
</para>
-<screen>
-<command>cvs add legalnotice-opl-<replaceable>pt_BR</replaceable>.xml</command>
-<command>cvs ci -m 'Added legal notice for <replaceable>pt_BR</replaceable>' legalnotice-opl-<replaceable>pt_BR</replaceable>.xml</command>
-</screen>
+ <screen><command><![CDATA[cvs add legalnotice-*-]]><replaceable>pt_BR</replaceable><![CDATA[.xml]]></command>
+<command><![CDATA[cvs ci -m 'Added legal notices for ]]><replaceable>pt_BR</replaceable><![CDATA[' legalnotice-*-]]><replaceable>pt_BR</replaceable><![CDATA[.xml]]></command></screen>
</step>
<step>
@@ -144,10 +151,8 @@
folder:
</para>
-<screen>
-<command>cd docs-common/images/</command>
-<command>cp watermark-en_US.svg watermark-<replaceable>pt_BR</replaceable>.svg</command>
-</screen>
+ <screen><command><![CDATA[cd docs-common/images/]]></command>
+<command><![CDATA[cp watermark-en_US.svg watermark-]]><replaceable>pt_BR</replaceable><![CDATA[.svg]]></command></screen>
<para>
Translate the <sgmltag class="element">text</sgmltag>
@@ -156,11 +161,9 @@
the results:
</para>
-<screen>
-<command>make watermark-<replaceable>pt_BR</replaceable>.png</command>
-<command>cvs add watermark-<replaceable>pt_BR</replaceable>*</command>
-<command>cvs ci -m 'Added <replaceable>pt_BR</replaceable> images' Makefile watermark-<replaceable>pt_BR</replaceable>*</command>
-</screen>
+ <screen><command><![CDATA[make watermark-]]><replaceable>pt_BR</replaceable><![CDATA[.png]]></command>
+<command><![CDATA[cvs add watermark-]]><replaceable>pt_BR</replaceable><![CDATA[*]]></command>
+<command><![CDATA[cvs ci -m ]]>'Added <replaceable>pt_BR</replaceable> images'<![CDATA[ Makefile watermark-]]><replaceable>pt_BR</replaceable><![CDATA[*]]></command></screen>
</step>
</procedure>
@@ -175,37 +178,58 @@
<section id="sn-translating-with-apps">
<title>Using Translation Applications</title>
+ <para>The <filename class="directory">po/</filename> directory
+ contains the <filename class="extension">.po</filename> files used
+ to translate content. It also contains a <filename
+ class="extension">.pot</filename> file, or PO template, which is
+ used to create new <filename class="extension">.po</filename>
+ files when necessary.</para>
<para>
If the <filename class="directory">po/</filename> directory does
not exist, you can create it and the translation template file
with the following commands:
</para>
-<screen>
-<command>mkdir po</command>
-<command>cvs add po/</command>
-<command>make pot</command>
+ <screen><command><![CDATA[mkdir po]]></command>
+<command><![CDATA[cvs add po/]]></command>
+<command><![CDATA[make pot]]></command>
</screen>
+ <caution>
+ <title>Do Not Make Manual POT Changes</title>
+ <para>Authors and editors generate the POT file from the source
+ XML files, which overwrite any manual changes to a POT file. If
+ you find a problem in the original messages of a POT file, visit
+ &BZ; at &BZ-URL; to file a bug against the document.</para>
+ </caution>
+
<para>
To work with a <filename class="extension">.po</filename> editor
like <application>KBabel</application> or
<application>gtranslator</application>, follow these
- steps:
+ steps.
</para>
+ <note>
+ <title>Example Locale is <replaceable>pt_BR</replaceable></title>
+ <para>The following examples use the locale code
+ <replaceable>pt_BR</replaceable>. Substitute your locale code
+ in these commands as necessary.</para>
+ </note>
+
+
<procedure>
<step>
+ <title>Change Directory</title>
<para>
In a terminal, go to the directory of the document you want
to translate:
</para>
-<screen>
-<command>cd ~/docs/example-tutorial</command>
-</screen>
+ <screen><command><![CDATA[cd ~/docs/example-tutorial]]></command></screen>
</step>
<step>
+ <title>Add Locale to List</title>
<para>To add your locale, you must locate and change the
appropriate locale list. Some documents are using the
<filename>po/LINGUAS</filename> file, as standardized in the
@@ -213,133 +237,107 @@
been updated to this standard yet. If you find the module
you are translating has not been updated, notify the &FDP;
or file a bug using &BZ;.</para>
- <para>In the <filename>po/LINGUAS</filename>, add your
- translation language code to the list. <emphasis>Keep the
- list in alphabetical order.</emphasis></para>
+ <para>Add your translation language code to the list in the
+ <filename>po/LINGUAS</filename> file. <emphasis>Keep the list
+ in alphabetical order.</emphasis></para>
</step>
<step>
+ <title>Create PO File</title>
<para>
Make a new <filename class="extension">.po</filename> file
for your locale:
</para>
-<screen>
-<command>make po/<replaceable>pt_BR</replaceable>.po</command>
-</screen>
+ <screen><command><![CDATA[make po/]]><replaceable>pt_BR</replaceable><![CDATA[.po]]></command></screen>
</step>
<step>
+ <title>Translate Strings</title>
<para>
- Now you can translate the file using the same application
- used to translate software:
+ To translate the file, use the same application used to
+ translate software:
</para>
-<screen>
-<command>kbabel po/<replaceable>pt_BR</replaceable>.po</command>
-</screen>
+ <screen><command><![CDATA[kbabel po/]]><replaceable>pt_BR</replaceable><![CDATA[.po]]></command></screen>
- <section id="sn-check-integrity">
+ </step>
+ <step>
<title>Check Integrity</title>
<para>
- Once you finish your work, it it time to commit. However one more step to go before committing your file.
- </para>
- <para>
- Please do check integrity with the following command. If no error, now you can commit. This ensures sane build (where $Lang, replace your language code such as 'ja' without the quotes).
- </para>
-<screen>
-<command>cd release-notes/devel/</command>
-<command>make validate-xml-$LANG</command>
-</screen>
- <para>
- It may take a while to complete. The $LANG/ directory is created if no error. Under this direcotry the translated xml files are generated from .po file.
+ Before committing your changes, check the integrity of the XML
+ with the following command. This ensures a sane build for all
+ users.
</para>
- </section>
-
- <section id="sn-build-html">
- <title>Build Html</title>
- <para>
- Instead 'make validate-xml-$LANG', the html can be generated. So that you can have a proofreading in html format.
- </para>
-
-<screen>
-<command>cd release-notes/devel/</command>
-<command>make html-<replaceable>$LANG</replaceable></command>
-</screen>
-
+ <screen><command><![CDATA[make html-]]><replaceable>pt_BR</replaceable></command></screen>
+ <para>You can read the resulting HTML files with a Web
+ browser.</para>
<important>
+ <title>Always Test Your Translation</title>
<para>
- Any error must be corrected before comitting. Erroneous changes can break documents for other users, editors, and automated applications.</para>
+ Do not go to the next step or commit changes until you test
+ your work in this step. Erroneous changes can break
+ documents for other users, editors, and automated
+ applications.</para>
</important>
-
- <para>
+ </step>
+ <step>
+ <title>Commit Work</title>
+ <para>
When you have finished your translation, commit the <filename class="extension">.po</filename> file. You may note the percent complete or some other useful message at commit time.
</para>
-<screen>
-<command>cvs ci -m <replaceable>'Translating... 400/10/126' </replaceable>po/<replaceable>ja</replaceable>.po</command>
-</screen>
-
-<!-- Is this deprecated?
- <para>
- <emphasis>Do not commit the <filename>Makefile</filename>
- until your translation is finished.</emphasis> To do so,
- run this command:
- </para>
-
-<screen>
-<command>cvs ci -m 'Translation to <replaceable>pt_BR</replaceable> finished' Makefile</command>
-</screen>
--->
+ <screen><command><![CDATA[cvs ci -m ]]><replaceable>'Translating... 400/10/126'</replaceable><![CDATA[ po/]]><replaceable>pt_BR</replaceable><![CDATA[.po]]></command></screen>
- <caution>
- <title>Do Not Make Manual POT Changes</title>
- <para>Authors and editors generate the POT file from the
- source XML files, which overwrite any manual changes to a
- POT file. If you find a problem in the original messages
- of a POT file, visit &BZ; at &BZ-URL; to file a bug
- against the document.</para>
- </caution>
+ </step>
+ </procedure>
</section>
- <section id="sn-waht-to-translate">
- <title>What to translate</title>
+ <section id="sn-what-to-translate">
+ <title>What to Translate</title>
<para>
- The most important docs modules/directories for each release are the following:
+ The most important docs modules/directories for each release are
+ the following:
</para>
<itemizedlist>
- <listitem>
- <para>docs-common/common/entities</para>
- </listitem>
- <listitem>
- <para>release-notes/devel</para>
- </listitem>
- <listitem>
- <para>homepage/devel</para>
- </listitem>
- <listitem>
- <para>install-guide/devel</para>
- </listitem>
- <listitem>
- <para>about-fedora/devel</para>
- </listitem>
- <listitem>
- <para>readme/devel</para>
- </listitem>
- <listitem>
- <para>readme-burning-isos/devel</para>
- </listitem>
- <listitem>
- <para>readme-live-image/devel</para>
- </listitem>
+ <listitem>
+ <para><filename
+ class="directory">docs-common/common/entities</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename
+ class="directory">release-notes/devel</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename
+ class="directory">homepage/devel</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename
+ class="directory">install-guide/devel</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename
+ class="directory">about-fedora/devel</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename class="directory">readme/devel</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename
+ class="directory">readme-burning-isos/devel</filename></para>
+ </listitem>
+ <listitem>
+ <para><filename
+ class="directory">readme-live-image/devel</filename></para>
+ </listitem>
</itemizedlist>
- <para>
- To see all documents available in our repo, run:
- </para>
-<screen>
-<command>export CVSROOT=:ext:username at cvs.fedoraproject.org:/cvs/docs</command>
-<command>cvs co -c</command>
-</screen>
+ <para>
+ To see all documents available in our repo, run:
+ </para>
+
+ <screen><command><![CDATA[export CVSROOT=:ext:]]><replaceable>username</replaceable><![CDATA[@cvs.fedoraproject.org:/cvs/docs]]></command>
+<command><![CDATA[cvs co -c]]></command></screen>
</section>
More information about the Fedora-docs-commits
mailing list