translation-quick-start-guide translation-quick-start-en.xml, 1.4, 1.5
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Sat Jan 21 02:35:07 UTC 2006
Author: pfrields
Update of /cvs/docs/translation-quick-start-guide
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv4272/translation-quick-start-guide
Modified Files:
translation-quick-start-en.xml
Log Message:
First round of editing, bump to 0.1
Index: translation-quick-start-en.xml
===================================================================
RCS file: /cvs/docs/translation-quick-start-guide/translation-quick-start-en.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- translation-quick-start-en.xml 19 Jan 2006 01:34:20 -0000 1.4
+++ translation-quick-start-en.xml 21 Jan 2006 02:35:00 -0000 1.5
@@ -1,4 +1,4 @@
-
+<!-- $Id: -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
@@ -7,11 +7,9 @@
%FEDORA-ENTITIES-EN;
<!ENTITY DOCNAME "translation-quick-start-guide">
- <!ENTITY DOCVERSION "0.0.2">
- <!ENTITY DOCDATE "2005-12-20">
+ <!ENTITY DOCVERSION "0.1">
+ <!ENTITY DOCDATE "2006-01-20">
<!ENTITY DOCID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)">
- <!-- this will soon vanish -->
- <!ENTITY BOOKID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)">
<!ENTITY FCLOCALVER "4">
@@ -23,298 +21,454 @@
&FDP-INFO;
-<section id="sn_intro">
+ <section id="sn_intro">
<title>Introduction</title>
-
+
<para>
- This guide intends to be a fast, simple step by step set of instructions to
- start contributing with the translation of Fedora Project's software and
- documents. Those interested in getting a better understanding of the
- translation process involved can see the Translation guide or refer to the
- manual of the specific translation tool.
+ This guide is a fast, simple, step-by-step set of instructions for
+ translating &FP; software and documents. If you are interested in
+ better understanding the translation process involved, refer to
+ the Translation guide or the manual of the specific translation
+ tool.
</para>
+
+ </section>
-</section>
-
-<section id="sn_accounts">
+ <section id="sn_accounts">
<title>Accounts and subscriptions</title>
<para>
- To participate in the Fedora Project as a translator you need an account.
- You can apply for an account at <ulink
- url="http://i18n.redhat.com/cgi-bin/i18n-signup/">
- http://i18n.redhat.com/cgi-bin/i18n-signup/</ulink>. You need to provide a
- username (login), an e-mail address, a target language -most likely your
- native language-, and the public part of your ssh key.
+ To participate in the &FP; as a translator you need an account.
+ You can apply for an account at <ulink
+ url="http://i18n.redhat.com/cgi-bin/i18n-signup/"/>. You need to
+ provide a user name (login), an email address, a target language
+ — most likely your native language — and the public
+ part of your SSH key.
</para>
<para>
- If you do not have a ssh key yet, you can generate one using the following steps:
- </para>
- <para>
- 1. Type in a comand line:
- </para>
- <screen>
- <command>ssh-keygen -t dsa</command>
- </screen>
- <para>
- Accept the default location (~/.ssh/id_dsa) and enter a passphrase.
+ If you do not have a SSH key yet, you can generate one using the
+ following steps:
</para>
- <caution>
-<title>Note</title>
-<para>
-Do not forget this passphrase as you will need it to access to the CVS
-repository.
-</para>
-</caution>
-<para>
-2. Copy the key to the appropiate file:
-</para>
+
+ <procedure>
+ <step>
+ <para>
+ Type in a comand line:
+ </para>
+
+<screen>
+<command>ssh-keygen -t dsa</command>
+</screen>
+
+ <para>
+ Accept the default location
+ (<filename>~/.ssh/id_dsa</filename>) and enter a passphrase.
+ </para>
+ <caution>
+ <title>Note</title>
+ <para>
+ Do not forget this passphrase as you will need it to access
+ to the CVS repository.
+ </para>
+ </caution>
+ </step>
+
+<!-- Are you sure this next step is necessary? My understanding is that -->
+<!-- this step would only be useful for authorizing you to SSH in from -->
+<!-- another host with your private key.
+
+ <step>
+ <para>
+ Copy the key to the appropiate file:
+ </para>
+
<screen>
<command>cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys</command>
</screen>
-<para>
-3. Change permissions to your key and .ssh directory:
-</para>
+
+ </step>
+
+-->
+ <step>
+ <para>
+ Change permissions to your key and <filename>.ssh</filename>
+ directory:
+ </para>
+
<screen>
<command>chmod 755 ~/.ssh</command>
-<command>chmod 644 ~/.ssh/authorized_keys</command>
+<!-- SEE ABOVE... <command>chmod 644 ~/.ssh/authorized_keys</command> -->
</screen>
-<para>
-Next, copy and paste the ssh key in the space provided in order to complete the
-account application.
-</para>
-<para>
-There are also two lists where you can discuss translation issues.
-fedora-trans-list is a general list to discuss problems that affect all
-languages; the second is the language-specific list (ex. fedora-trans-es for
-Spanish language) to discuss issues that affect only the individual community of
-translators. It is also useful to subscribe to fedora-doc-list to be informed of issues concerning the general documentation.
-</para>
-</section>
-
-<section id="sn_translating_software">
-<title>Translating software</title>
-
-<para>
-The translatable part of a software package is available in one or more po files. Fedora
-Project stores these files in a CVS repository under the directory /translate.
-Once your account has been approved, you can download this directory typing the
-following instructions in a command line:
-</para>
+
+ </step>
+ <step>
+ <para>
+ Copy and paste the ssh key in the space provided in order to
+ complete the account application.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ There are also two lists where you can discuss translation issues.
+ The first is <firstterm>fedora-trans-list</firstterm>, a general
+ list to discuss problems that affect all languages. Refer to
+ <ulink url="http://www.redhat.com/archives/fedora-trans-list"/>
+ for more information. The second is the language-specific list,
+ such as <firstterm>fedora-trans-es</firstterm> for Spanish
+ translators, to discuss issues that affect only the individual
+ community of translators.
+ </para>
+ <para>
+ You may also find it useful to subscribe to
+ <firstterm>fedora-docs-list</firstterm> to stay informed about
+ general documentation issues.
+ </para>
+ </section>
+
+ <section id="sn_translating_software">
+ <title>Translating software</title>
+
+ <para>
+ The translatable part of a software package is available in one or
+ more <filename>po</filename> files. The &FP; stores these files in
+ a CVS repository under the directory
+ <filename>translate/</filename>. Once your account has been
+ approved, download this directory typing the following
+ instructions in a command line:
+ </para>
+
<screen>
<command>export CVS_RSH=ssh</command>
-<command>export CVSROOT=:ext:[username]@i18.redhat.com:/usr/local/CVS</command>
+<command>export CVSROOT=:ext:<replaceable>username</replaceable>@i18.redhat.com:/usr/local/CVS</command>
<command>cvs -z9 co translate/</command>
</screen>
-<para>
-All the modules and po files will be downloaded to your machine following the
-same hierarchy of the repository. Each directory contains a pot file
-(ex. anaconda.pot) and the po files for each language (af.po, de.po, es.po,
-etc).
-</para>
-<para>
-You can check the status of the translations at
-<ulink
-url="http://i18n.redhat.com/cgi-bin/i18n-status">http://i18n.redhat.com/cgi-bin/i18n-status</ulink>.
-Choose your language in the dropdown menu or check the
-overall status. You can click on each package to view the maintainer and the name
-of the last translator of this module. If you want to translate a module,
-contact your language-specific list and let your community know you are working
-on that module. Afterwards, press [take] in the status page. The
-module will be assigned to you. When asked for a password, enter the one you
-have received via e-mail after applying for the account.
-</para>
-<para>
-You can now start translating:
-</para>
-<para>
-1. Go to the directory of the package you have taken.
-</para>
-<screen>
-<command>cd ~/translate/[package_name]</command>
-</screen>
-<para>
-2. Update the files with the command:
-</para>
+
+ <para>
+ These commands download all the modules and
+ <filename>.po</filename> files to your machine following the same
+ hierarchy of the repository. Each directory contains a
+ <filename>.pot</filename> file, such as
+ <filename>anaconda.pot</filename>, and the
+ <filename>.po</filename> files for each language, such as
+ <filename>zh_CN.po</filename>, <filename>de.po</filename>, and so
+ forth.
+ </para>
+ <para>
+ You can check the status of the translations at <ulink
+ url="http://i18n.redhat.com/cgi-bin/i18n-status"/>. Choose your
+ language in the dropdown menu or check the overall status. Select
+ a package to view the maintainer and the name of the last
+ translator of this module. If you want to translate a module,
+ contact your language-specific list and let your community know
+ you are working on that module. Afterwards, select
+ <literal>take</literal> in the status page. The module is then
+ assigned to you. At the password prompt, enter the one you
+ received via e-mail when you applied for your account.
+ </para>
+ <para>
+ You can now start translating.
+ </para>
+ <procedure>
+ <step>
+ <para>
+ Go to the directory of the package you have taken.
+ </para>
+
+<screen>
+<command>cd ~/translate/<replaceable>package_name</replaceable></command>
+</screen>
+
+ </step>
+ <step>
+ <para>
+ Update the files with the following command:
+ </para>
+
<screen>
<command>cvs up</command>
</screen>
-<para>
-3. Translate the po file of your language in a po editor like KBabel,
-gtranslator, etc. For example, to open the po file for Spanish in kbabel, type:
-</para>
+
+ </step>
+ <step>
+ <para>
+ Translate the po file of your language in a po editor such as
+ <application>KBabel</application> or
+ <application>gtranslator</application>. For example, to open
+ the <filename>.po</filename> file for Spanish in
+ <application>KBabel</application>, type:
+ </para>
+
<screen>
<command>kbabel es.po</command>
</screen>
-<para>
-4. When you finish your work, commit your changes back to the repository:
-</para>
-<screen>
-<command>cvs commit -m 'comments' [lang].po</command>
-</screen>
-<para>
-5. As a last step, release the module in the status page clicking on the
-[release] link so other people can work on it.
-</para>
-<para>
-If you want to proofread your translation as part of the software, follow these steps:
-</para>
-<para>
-1. Go to the directory of the package you want to proofread:
-</para>
-<screen>
-<command>cd ~/translate/[package_name]</command>
-</screen>
-<para>
-2. Convert the .po file in .mo file with msgfmt:
-</para>
-<screen>
-<command>msgfmt [lang].po</command>
-</screen>
-<para>
-3. Overwrite the existing .mo file in /usr/share/locale/[lang]/LC_MESSAGES/ .
-Firstly, make sure to back up the existing file:
-</para>
-<screen>
-<command>cp /usr/share/locale/[lang]/LC_MESSAGES/[package_name].mo [package_name].mo-backup</command>
-<command>mv [package_name].mo /usr/share/locale/[lang]/LC_MESSAGES/</command>
-</screen>
-<para>
-4. Proofread the package with the translated strings as part of the application:
-</para>
-<screen>
-<command>LANG=[lang] rpm -qi [package_name]</command>
-</screen>
-<para>
-The application related to the translated package will run with the translated strings.
-</para>
-</section>
-
-<section id="sn_translating_docs">
-<title>Translating documentation</title>
-
-<para>
-The Fedora documentation is also stored in a CVS repository under the directory /docs. The
-process to download the documentation is similar to the one used to download po
-files:
-</para>
+
+ </step>
+ <step>
+ <para>
+ When you finish your work, commit your changes back to the
+ repository:
+ </para>
+
+<screen>
+<command>cvs commit -m 'comments' <replaceable>lang</replaceable>.po</command>
+</screen>
+
+ </step>
+ <step>
+ <para>
+ As a last step, click the <literal>release</literal> link on
+ the status page to release the module so other people can work
+ on it.
+ </para>
+ </step>
+ </procedure>
+ <para>
+ If you want to proofread your translation as part of the software,
+ follow these steps:
+ </para>
+ <procedure>
+ <step>
+ <para>
+ Go to the directory of the package you want to proofread:
+ </para>
+
+<screen>
+<command>cd ~/translate/<replaceable>package_name</replaceable></command>
+</screen>
+
+ </step>
+ <step>
+ <para>
+ Convert the <filename>.po</filename> file in
+ <filename>.mo</filename> file with <command>msgfmt</command>:
+ </para>
+
<screen>
-<command>export CVSROOT=:ext:[username]@cvs.fedora.redhat.com:/cvs/docs</command>
+<command>msgfmt <replaceable>lang</replaceable>.po</command>
+</screen>
+
+ </step>
+ <step>
+ <para>
+ Overwrite the existing <filename>.mo</filename> file in
+ <filename>/usr/share/locale/<replaceable>lang</replaceable>/LC_MESSAGES/</filename>.
+ First, back up the existing file:
+ </para>
+
+<screen>
+<command>cp /usr/share/locale/<replaceable>lang</replaceable>/LC_MESSAGES/<replaceable>package_name</replaceable>.mo <replaceable>package_name</replaceable>.mo-backup</command>
+<command>mv <replaceable>package_name</replaceable>.mo /usr/share/locale/<replaceable>lang</replaceable>/LC_MESSAGES/</command>
+</screen>
+
+ </step>
+ <step>
+ <para>
+ Proofread the package with the translated strings as part of
+ the application:
+ </para>
+
+<screen>
+<command>LANG=<replaceable>lang</replaceable> rpm -qi <replaceable>package_name</replaceable></command>
+</screen>
+
+ </step>
+ </procedure>
+ <para>
+ The application related to the translated package will run with
+ the translated strings.
+ </para>
+ </section>
+
+ <section id="sn_translating_docs">
+ <title>Translating documentation</title>
+
+ <para>
+ The Fedora documentation is also stored in a CVS repository under
+ the directory <filename>docs/</filename>. The process to download
+ the documentation is similar to the one used to download
+ <filename>.po</filename> files:
+ </para>
+
+<screen>
+<command>export CVSROOT=:ext:<replaceable>username</replaceable>@cvs.fedora.redhat.com:/cvs/docs</command>
<command>cvs co docs</command>
</screen>
-<para>
-This will download all the current documents in the directory. If you want to
-download only the document you are interested to translate, list the current
-documents in the repository and then check out the directory containing the
-document you want:
-</para>
+
+ <para>
+ This step downloads all the current documents in the directory. To
+ download only a single document 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
+ check document validity for building.
+ </para>
+
<screen>
<command>cvs co -c</command>
-<command>cvs co example-tutorial</command>
+<command>cvs co example-tutorial docs-common</command>
+</screen>
+
+ <para>
+ The documents are written in DocBook XML format and named using
+ the specific-language locale, such as
+ <filename>example-tutorial-en.xml</filename>. If you plan to
+ translate directly from the original XML file, you should create
+ the document for your language:
+ </para>
+
+<screen>
+<command>cp example-tutorial-en.xml example-tutorial-<replaceable>es</replaceable>.xml</command>
</screen>
-<para>
-The documents are written in xml format (docBook to be precise) and named using
-the specific-language locale: example-tutorial-en.xml. If you are planning to
-translate directly from the original xml file, you should create the document for your
-language; for instance:
-</para>
-<screen>
-<command>cp example-tutorial-en.xml example-tutorial-es.xml</command>
-</screen>
-<para>
-Afterwards you can work on the new copy.
-</para>
-<para>
-You can also convert the xml files into po files and work with a po editor
-like KBabel o gtranslator. To do so, follow these steps:
-</para>
-<para>
-1. In a terminal, go to the directory of the document you
-want to translate:
-</para>
+
+ <para>
+ Afterwards you can work on the new copy.
+ </para>
+ <para>
+ You can also convert the XML files into <filename>.po</filename>
+ files and work with a <replaceable>.po</replaceable> editor like
+ <application>KBabel</application> or
+ <application>gtranslator</application>. To do so, follow these
+ steps:
+ </para>
+ <procedure>
+ <step>
+ <para>
+ In a terminal, go to the directory of the document you want to
+ translate:
+ </para>
+
<screen>
<command>cd ~/docs/example-tutorial</command>
</screen>
-<para>
-2. Extract the translatable strings with xml2pot:
-</para>
-<screen>
-<command>xml2pot example-tutorial-en.xml > [lang].po</command>
-</screen>
-<para>
-3. Now you can translate the file using the same application used to translate
-software:
-</para>
-<screen>
-<command>kbabel [lang].po</command>
-</screen>
-<para>
-4. Once you finish, it is necessary to convert the translated .po file to .xml file in the target
-language with po2xml:
-</para>
-<screen>
-<command>po2xml example-tutorial-en.xml [lang].po > example-tutorial-[lang].xml</command>
-</screen>
-<para>
-As the filter (xml2po) does not include entities in the .po file, you have to
-change the language of the document from English:
-</para>
-<para><article id="example-tutorial" lang="en"></para>
-<para>to your language:</para>
-<para><article id="example-tutorial" lang="es"></para>
-
-<para>
-When the translated file is ready, add it to the repository:
-</para>
-<screen>
-<command>cvs add example-tutorial-[lang].xml</command>
-<command>cvs commit -m 'any comment' example-tutorial-[lang].xml</command>
-</screen>
-<para>
-As a final step, you may have to change the Makefile so the document can be
-built in HTML and PDF formats.
-</para>
-<caution>
-<title>Note:</title>
-<para>
-Please advise fedora-doc-list and fedora-trans-[locale] that you are modifying
-the Makefile. You should tell your community that you are working on the
-translation of this document before you start translating to avoid that
-different people work on the same file.
-</para>
-</caution>
-<para>
-1. In the text editor of your preference, open the Makefile.
-</para>
+
+ </step>
+ <step>
+ <para>
+ Extract the translatable strings with xml2pot:
+ </para>
+
+<screen>
+<command>xml2pot example-tutorial-en.xml > <replaceable>lang</replaceable>.po</command>
+</screen>
+
+ </step>
+ <step>
+ <para>
+ Now you can translate the file using the same application used
+ to translate software:
+ </para>
+
+<screen>
+<command>kbabel <replaceable>lang</replaceable>.po</command>
+</screen>
+
+ </step>
+ <step>
+ <para>
+ Once you finish, it is necessary to convert the translated
+ <filename>.po</filename> file to <filename>.xml</filename>
+ file in the target language with <command>po2xml</command>:
+ </para>
+
+<screen>
+<command>po2xml example-tutorial-en.xml <replaceable>lang</replaceable>.po > example-tutorial-<replaceable>lang</replaceable>.xml</command>
+</screen>
+
+ </step>
+ </procedure>
+ <para>
+ The <command>xml2po</command> filter does not include entities
+ in the <filename>.po</filename> file. You must change the
+ language of the document. Locate a line like the following near
+ the top of the document:
+ </para>
+
+<screen>
+<computeroutput><article id="example-tutorial" lang="en"></computeroutput>
+</screen>
+
+ <para>Change the attribute to your language:</para>
+
+<screen>
+<computeroutput><article id="example-tutorial" lang="<replaceable>es</replaceable>"></computeroutput>
+</screen>
+
+ <para>
+ When the translated file is ready, add it to the repository:
+ </para>
+
+<screen>
+<command>cvs add example-tutorial-<replaceable>lang</replaceable>.xml</command>
+<command>cvs commit -m '<replaceable>Any comment</replaceable>' example-tutorial-<replaceable>lang</replaceable>.xml</command>
+</screen>
+
+ <para>
+ You may have to change the <filename>Makefile</filename> so the
+ document can be built in HTML and PDF formats.
+ </para>
+ <caution>
+ <title>Note:</title>
+ <para>
+ Please advise the community through fedora-doc-list and
+ fedora-trans-<replaceable>locale</replaceable> that you are
+ modifying the <filename>Makefile</filename>. Inform the
+ community that you are working on the translation of this
+ document before you begin, to avoid conflict between translators
+ working on the same file.
+ </para>
+ </caution>
+
+ <procedure>
+ <step>
+ <para>
+ In the text editor of your preference, open the
+ <filename>Makefile</filename>.
+ </para>
+
<screen>
<command>vi Makefile</command>
</screen>
-<para>
-2. Add the locale of the new translation after the other languages as in the
-following example:
-</para>
-<para>
-LANGUAGES = en de [lang]
-</para>
-<para>
-3. Include also the following lines:
-</para>
-<para>
-DOCTITLE-[lang] = [name of tutorial]
-XMLEXTRAFILES-[lang]=
-</para>
-<para>
-4. Commit the Makefile
-</para>
-<screen>
-<command>cvs commit -m 'any comment' Makefile</command>
-</screen>
-<para>
-Then, you can build the document in your machine by typing:
-</para>
+ </step>
+ <step>
+ <para>
+ Add the locale of the new translation after the other
+ languages as in the following example:
+ </para>
+
+<screen>
+<computeroutput>LANGUAGES = en de <replaceable>lang</replaceable>
+</screen>
+
+ </step>
+ <step>
+ <para>
+ Commit the <filename>Makefile</filename>.
+ </para>
+
<screen>
-<command>make</command>
+<command>cvs commit -m '<replaceable>Any comment</replaceable>' Makefile</command>
</screen>
-</section>
+
+ </step>
+ <step>
+ <para>
+ Then, you can build the document in your langugage by typing:
+ </para>
+
+<screen>
+<command>make html-<replaceable>lang</replaceable></command>
+</screen>
+
+ </step>
+ </procedure>
+
+ </section>
+
</article>
+
+<!--
+Local variables:
+mode: xml
+fill-column: 72
+End:
+-->
More information about the Fedora-docs-commits
mailing list