translation-quick-start-guide translation-quick-start-en.xml, NONE, 1.1

[Manuel Ospina (mospina)]

Author: mospina

Update of /cvs/docs/translation-quick-start-guide
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv22988

Added Files:
	translation-quick-start-en.xml 
Log Message:
trans-quick


--- NEW FILE translation-quick-start-en.xml ---

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

 <!ENTITY % FEDORA-ENTITIES-EN SYSTEM
 "../docs-common/common/fedora-entities-en.ent">
 %FEDORA-ENTITIES-EN;

 <!ENTITY DOCNAME "translation-quick-start-guide">
 <!ENTITY DOCVERSION "0.0.2">
 <!ENTITY DOCDATE "2005-12-20">
 <!ENTITY DOCID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)">
 <!-- this will soon vanish -->
 <!ENTITY BOOKID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)">

 <!ENTITY FCLOCALVER "4">

 ]>
 
<article id="translation-quickstart-guide" lang="en">
	<articleinfo>
		<title>Translation Quick Start Guide</title>
		<copyright>
			<year>2005</year>
			<holder>&FORMAL-RHI;</holder>
			<holder>Manuel Ospina</holder>
		</copyright>
		<authorgroup>
			<author>
				<surname>Ospina</surname>
				<firstname>Manuel</firstname>
			</author>
		</authorgroup>
		&LEGALNOTICE;
	</articleinfo>

<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.
    </para>

</section>

<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. 
    </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.
    </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>
<screen>
<command>cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys</command>
</screen>
<para>
3. Change permissions to your key and .ssh directory:
</para>
<screen>
<command>chmod 755 ~/.ssh</command>
<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>
<screen>
<command>export CVS_RSH=ssh</command>
<command>export CVSROOT=:ext:[username]@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>
<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>
<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>
<screen>
<command>export CVSROOT=:ext:[username]@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>
<screen>
<command>cvs co -c</command>
<command>cvs co example-tutorial</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>
<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>
<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>
<screen>
<command>make</command>
</screen>
</section>
</article>