translation-quick-start-guide/en_US translation-quick-start.xml, NONE, 1.1

Author: pfrields

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

Added Files:
	translation-quick-start.xml 
Log Message:
Add proper en_US locale notation and correct support files


--- NEW FILE translation-quick-start.xml ---
<!-- $Id: -->
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/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.2.2.2">
 <!ENTITY DOCDATE "2006-02-13">
 <!ENTITY DOCID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)">

 <!ENTITY FCLOCALVER "4">

 ]>

<article id="translation-quickstart-guide" lang="en_US">

  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="fdp-info.xml"/>

  <section id="sn-intro">
    <title>Introduction</title>
    
    <para>
      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>
    
    &BUG-REPORTING;

  </section>

  <section id="sn_accounts">
    <title>Accounts and Subscriptions</title>

    <para>
      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, an email address, a target language &mdash;
      most likely your native language &mdash; 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>

    <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>Don't Forget Your Passphrase!</title>
	  <para>
	    You will need your passphrase to access to the CVS
	    repository.  It cannot be recovered if you forget it.
	  </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>

      </step>

-->
      <step>
	<para>
	  Change permissions to your key and <filename>.ssh</filename>
	  directory:
	</para>

<!-- Why is this permission 755?  The 700 mode is usually recommended -->
<!-- for ~/.ssh/ for extra protection, since it does house an SSH -->
<!-- private key. -->

<screen>
<command>chmod 700 ~/.ssh</command><!-- SEE ABOVE... <command>chmod
644 ~/.ssh/authorized_keys</command> -->
</screen>

      </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>
    <tip>
      <title>General Documentation Issues</title>
      <para>
	You may also find it useful to subscribe to
	<firstterm>fedora-docs-list</firstterm> to stay informed about
	general documentation issues.
      </para>
    </tip>
  </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:<replaceable>username</replaceable>@i18n.redhat.com:/usr/local/CVS</command>

<command>cvs -z9 co translate/</command>
</screen>

    <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>

    <section id="sn-translating-strings">
      <title>Translating Strings</title>

      <procedure>
	<step>
	  <para>
	    Change directory to the location 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>

	</step>
	<step>
	  <para>
	    Translate the <filename>.po</filename> file of your language
	    in a <filename>.po</filename> 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>

	</step>
	<step>
	  <para>
	    When you finish your work, commit your changes back to the
	    repository:
	  </para>

<screen>
<command>cvs commit -m '<replaceable>comments</replaceable>'
<replaceable>lang</replaceable>.po</command>
</screen>

	</step>
	<step>
	  <para>
	    Click the <literal>release</literal> link on the status page
	    to release the module so other people can work on it.
	  </para>
	</step>
      </procedure>
    </section>

    <section id="sn-proofreading">
      <title>Proofreading</title>

      <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>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>

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

    <section id="sn-downloading-docs">
      <title>Downloading Documentation</title>

      <para>
	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 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 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>
	Afterwards you can work on the new copy.
      </para>

    </section>

    <section id="sn-translating-with-apps">
      <title>Using Translation Applications</title>

      <para>
	You can also convert the XML files into <filename>.po</filename>
	files and work with a <filename>.po</filename> 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>

	</step>
	<step>
	  <para>
	    Extract the translatable strings with
	    <command>xml2pot</command>:
	  </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, you must 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>
	<step>
	  <para>
	    The <command>xml2pot</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>&lt;article id="example-tutorial"
lang="en"&gt;</computeroutput>
</screen>

	</step>
	<step>
	  <para>Change the attribute to your language:</para>

<screen>
<computeroutput>&lt;article id="example-tutorial"
lang="<userinput><replaceable>es</replaceable></userinput>"&gt;</computeroutput>
</screen>

	</step>
	<step>
	  <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>

	</step>
      </procedure>

    </section>

    <section id="sn-changing-makefile">
      <title>Changing the <filename>Makefile</filename></title>

      <para>
	You may have to change the <filename>Makefile</filename> so the
	document can be built in HTML and PDF formats.
      </para>
      <important>
	<title>Avoid Translation Conflicts</title>
	<para>
	  Please advise the community through fedora-docs-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>
      </important>

      <procedure>
	<step>
	  <para>
	    In the text editor of your preference, open the
	    <filename>Makefile</filename>.
	  </para>

<screen>
<command>vi Makefile</command>
</screen>
	</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
<userinput><replaceable>lang</replaceable></userinput></computeroutput>
</screen>

	</step>
	<step>
	  <para>
	    Commit the <filename>Makefile</filename>.
	  </para>

<screen>
<command>cvs commit -m '<replaceable>Any comment</replaceable>'
Makefile</command>
</screen>

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

  </section>

</article>

<!--
Local variables:
mode: xml
fill-column: 72
End:
-->