Traducción de ayudas

Este documento describe los pasos a seguir para traducir las ayudas de las aplicaciones y utilidades de GNOME.

En todas las aplicaciones, apliques y utilidades del entorno GNOME se incluye un manual con la idea de facilitar su aprendizaje a los usuarios. Una vez traducidos los mensajes del interfaz, de los menús y de los diálogos, que suponen el primer contacto de los usuarios con la aplicación, nuestro objetivo es traducir la documentación que se adjunta con ella. Esta guía tiene por objetivo ayudar a los traductores a realizar esta labor de forma sencilla, empezando por aclarar los distintos ficheros que se deben traducir y terminado con la forma de entregar los trabajos en el repositorio SVN.

Con el fin de que la guía sea lo más practica posible, se usará las ayudas del aplique whereami y su traducción al castellano (código es) como ejemplo.

Ficheros de un manual

El original en inglés de la ayuda de whereami se encuentra en el directorio: gnome-applets/whereami/docs/C y se compone de los siguientes ficheros:

 ./C/whereami_applet.sgml
 ./C/whereami.sgml
 ./C/topic.dat
 ./C/whereami_applet-C.omf
 ./C/figures
 ./C/figures/whereami_applet.png

El resultado de la traducción deberá residir en el directorio: gnome-applets/whereami/docs/es manteniendo la misma estructura:

 ./es/whereami_applet.sgml
 ./es/whereami.sgml
 ./es/topic.dat
 ./es/whereami_applet-es.omf
 ./es/figures
 ./es/figures/whereami_applet.png
 ./es/authors.sgml
 ./es/license.sgml
 ./es/licencia-es.sgml
 ./es/licencia-nota-es.sgml

Observarás que hay tres ficheros adicionales en la traducción. Más adelante explicaremos el motivo.

El grueso de la traducción lo componen los ficheros de tipo sgml, debiéndose traducir también algunas frases en el resto de ficheros. Por último es necesario realizar las capturas en castellano de las figuras que se incluyen en el directorio figures.

Veremos en la sección dedicada a las entregas que, de cara a realizar una entrega en el repositorio, hay que prestar también atención a algunos ficheros adicionales.

En los paquetes de traducción que preparamos en Gnome-es, incluimos el árbol con el original en inglés y, en caso de existir una versión previa de la traducción, los ficheros correspondientes a la traducción anterior. Todo ello comprimido en un paquete de tipo tar.

Traducción de cada fichero

A continuación se describe cómo y qué traducir en cada fichero.

harem_applet.sgml

Este fichero es una especie de cabecera, y cuando existe (a veces está incluido todo en un único sgml), contiene información sobre el tipo de DTD usada por el documento, sobre la licencia y los derechos de autor.

 <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
 <!ENTITY whereami.sgml SYSTEM "whereami.sgml">

 ]>

 <article id="index"> <!-- please do not change the id -->

 <!-- ============= Document Header ============================= -->
 <artheader>
  <title>Where Am I? Applet</title>
  <copyright>
   <year>2000</year>
   <holder>Telsa Gwynne</holder>
  </copyright>

  <!-- translators: uncomment this:

  <copyright>
   <year>2000</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->

  <!-- do not put authorname in the header except in copyright - use
  section "authors" below -->

  <legalnotice id="legalnotice">
   <para>
    Permission is granted to copy, distribute and/or modify this
    document under the terms of the <citetitle>GNU Free Documentation

...

    of the GNOME Documentation Project, the names have been printed in caps
    or initial caps.
   </para>
  </legalnotice>

  <releaseinfo>
   This is version 1.0 of the Where Am I? applet manual.
  </releaseinfo>
 </artheader>

 <!-- ============= Document Body ============================= -->

 &whereami.sgml;

 </article>

En este fichero deberemos incluir una serie de nuevas definiciones en la cabecera DTD:

 <!ENTITY name "¿Dónde estoy?">
 <!ENTITY aplication "whereami">

 <!ENTITY authors SYSTEM "authors.sgml">
 <!ENTITY license SYSTEM "license.sgml">

 <!ENTITY licencia-nota-es SYSTEM "licencia-nota-es.sgml">
 <!ENTITY license-es SYSTEM "licencia-es.sgml">

 <!ENTITY programer "John Kodis">
 <!ENTITY programer-email "<email>kodis@jagunet.com</email>">

 <!ENTITY writer "Telsa Gwynne">
 <!ENTITY writer-email "<email>hobbit@aloss.ukuu.org.uk</email>">

 <!ENTITY traductor "Manuel de Vega Barreiro">
 <!ENTITY traductor-email "<email>mbarreiro@red.madritel.es</email>">

Iremos viendo el significado y uso de cada una de estas definiciones más adelante.

Después indicaremos que el documento está en castellano:

 <article id="index" lang="es"> <!-- please do not change the id -->

Incluiremos una nota sobre los derechos de autor de la traducción:

 <copyright>
  <year>2001</year>
  <holder>&traductor; (Traducción al Castellano)</holder>
 </copyright>

Observa que el nombre del traductor se toma de una de las definiciones de la cabecera DTD. De esta forma aunque el nombre aparezca varias veces a lo largo del manual sólo hay que mantenerlo actualizado en la cabecera. Fíjate en que el año de los derechos de autor de la traducción es el actual, y no tiene por qué coincidir con el del original.

El siguiente paso es traducir la información de la versión del manual:

 <releaseinfo>
 Ésta es la versión 1.0 del manual del aplique ¿Dónde estoy?
 </releaseinfo>

La nota acerca de la licencia no se traduce por motivos legales. En su lugar incluimos una traducción a título informativo, insertando el fichero licencia-nota-es.sgml:

 &licencia-nota-es;

La nota acerca de la licencia está disponible en la web de Gnome-es.

A continuación presentamos el resultado final de la traducción de este fichero:

 CTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
 <!ENTITY whereami.sgml SYSTEM "whereami.sgml">

 <!ENTITY name "¿Dónde estoy?">
 <!ENTITY aplication "whereami">

 <!ENTITY authors SYSTEM "authors.sgml">
 <!ENTITY license SYSTEM "license.sgml">

 <!ENTITY licencia-nota-es SYSTEM "licencia-nota-es.sgml">
 <!ENTITY license-es SYSTEM "licencia-es.sgml">

 <!ENTITY programer "John Kodis">
 <!ENTITY programer-email "<email>kodis@jagunet.com</email>">

 <!ENTITY writer "Telsa Gwynne">
 <!ENTITY writer-email "<email>hobbit@aloss.ukuu.org.uk</email>">

 <!ENTITY traductor "Manuel de Vega Barreiro">
 <!ENTITY traductor-email "<email>mbarreiro@red.madritel.es</email>">
 ]>

 &lt;article id="index" <userinput>lang="es"</userinput>&gt; &lt;!-- please do not change the id --&gt;

 &lt;!-- ============= Document Header ============================= --&gt;
 &lt;artheader&gt;
  &lt;title&gt;Aplique ¿Dónde estoy?&lt;/title&gt;
  &lt;copyright&gt;
   &lt;year&gt;2000&lt;/year&gt;
   &lt;holder&gt;&amp;writer;&lt;/holder&gt;
  &lt;/copyright&gt;
  &lt;copyright&gt;
   &lt;year&gt;2001&lt;/year&gt;
   &lt;holder&gt;&amp;traductor; (traducción al Castellano)&lt;/holder&gt;
  &lt;/copyright&gt;
  &lt;!-- do not put authorname in the header except in copyright - use
  section "authors" below --&gt;

  &lt;legalnotice id="legalnotice"&gt;
   &lt;para&gt;
    Permission is granted to copy, distribute and/or modify this
    document under the terms of the &lt;citetitle&gt;GNU Free Documentation

    ...

    of the GNOME Documentation Project, the names have been printed in caps
    or initial caps.
   &lt;/para&gt;
 &amp;licencia-nota-es;
 &lt;/legalnotice&gt;

  &lt;releaseinfo&gt;
   Ésta es la versión 1.o del manual del aplique ¿Dónde estoy?
  &lt;/releaseinfo&gt;
 &lt;/artheader&gt;

 &lt;!-- ============= Document Body ============================= --&gt;

 &amp;whereami.sgml;

 &lt;/article&gt;

whereami.sgml

Este fichero contiene el cuerpo principal del manual. Se traduce siguiendo las normas de traducción de ficheros docbook/sgml. Si no conoces este tipo de ficheros la FAQ de documentación del grupo Lilo (SGML/docbook) y los Trucos y ayudas para traducir documentos Linux te serán de gran ayuda.

Hay dos secciones con un tratamiento especial: la sección dedicada a los autores y la licencia.

La sección de autores básicamente es la misma en todos los documentos y para facilitar la labor de los traductores encontraréis en Gnome-es una propuesta de traducción.

Como es habitual se debe respetar la licencia en su formato original, y por este motivo sólo se incluye un traducción a titulo informativo. Nuevamente se dispone en Gnome-es de una [http://www.croftj.net/~barreiro/spanish/gnome-es/v1.4/ayudas/licencia-es.sgml propuesta de traducción] y una copia de la licencia original en inglés.

Estas últimas secciones (autores, licencia original y licencia traducida) se insertan añadiendo al final de la traducción los siguientes marcadores:

 &amp;authors;
 &amp;license;
 &amp;licencia-es;

De esta forma el documento traducido tendría la siguiente presentación:

 &lt;sect1 id="whereami"&gt;
  &lt;title&gt;Aplique ¿Dónde estoy?&lt;/title&gt;

   &lt;para&gt;
   El aplique &lt;application&gt;¿Dónde estoy?&lt;/application&gt;, mostrado en
   &lt;xref linkend="whereamiapplet-fig"&gt;, indica la posición del puntero
   del ratón en la pantalla, mostrando las coordenadas &lt;parameter&gt;x&lt;/parameter&gt;

   ...

    &lt;/itemizedlist&gt;
   &lt;/para&gt;
  &lt;/sect2&gt;


  &lt;!-- ============= Bugs ================================== --&gt;
  &lt;!-- This section should describe known bugs and limitations of
       the program if there are any - please be frank and list all
       problems you know of --&gt;

  &lt;sect2 id="whereami-bugs"&gt;
   &lt;title&gt;Errores y limitaciones conocidas&lt;/title&gt;
   &lt;para&gt;
    Este aplique no tiene errores conocidos.
   &lt;/para&gt;
  &lt;/sect2&gt;

 &amp;authors;
 &amp;license;
 &amp;licencia-es;

 &lt;/sect1&gt;

topic.dat

Este fichero se traduce rápido, basta traducir la etiqueta asignada al índice del documento.

 index.html      Aplique ¿Dónde estoy?

whereami_applet-es.omf

Este fichero también se traduce rápido, pero hay que tener cuidado, ya como observarás en primer lugar se le cambia de nombre.

 cp whereami_applet.omf whereami_applet-es.omf

Además no hay que traducir todo su contenido, sólo algunas partes:

  &lt;?xml version="1.0" standalone="no"?&gt;
  &lt;omf&gt;
  &lt;resource&gt;
    &lt;title&gt;
      <userinput>Manual del aplique ¿Dónde estoy?</userinput>
    &lt;/title&gt;
    &lt;subject&gt;
      &lt;category&gt;GNOME|Applets|Utility&lt;/category&gt;
    &lt;/subject&gt;
    &lt;format mime="text/sgml"/&gt;
    &lt;identifier url="whereami_applet.sgml"/&gt;
    &lt;language code="<userinput>es</userinput>"/&gt;
  &lt;/resource&gt;
  &lt;/omf&gt;

Como puedes ver el apartado 'category' no se traduce.

Figuras

Por último nos queda capturar las figuras, pero lógicamente en castellano. Los coordinadores del proyecto de documentación de GNOME (GDP) recomiendan usar el tema por defecto a la hora de realizar las capturas. Esto debería respetarse, ya que en el texto se hará mención a menús y botones, y si cambiamos a otros temas podrían tener una presentación diferente.

La revisión

En primer lugar, debemos precisar lo que entendemos por revisión: se trata de revisar la ortografía y el formato de los documentos que acabamos de traducir, y no de una revisión de estilo, tal y como la acometería un revisor.

Segunda lectura

Una cosa que siempre viene bien, una vez acabado el conjunto de la traducción, es leerla de nuevo. Os aseguro que en esta segunda lectura se mejoran y corrigen muchas cosas.

Corrector ortográfico

La siguiente fase de la revisión consiste en pasar un corrector ortográfico a los documentos traducidos. En las páginas de COES tenéis la última versión del diccionario ispell en Castellano.

Formato SGML

Por último, conviene comprobar que hemos respetado el formato Docbook/SGML al realizar la traducción. La mejor forma de conseguirlo es convertir nuestro recién revisado documento al formato html usando el siguiente comando:

 db2html whereami_applet.sgml

Al ejecutar este comando, un compilador que a partir del formato Docbook/SGML genera una versión del documento en formato html, podremos ver si existen errores en los marcadores.

Disponer del documento en formato html también facilita una lectura más placentera de la traducción.

La instalación de las herramientas y utilidades necesarias para este paso se describen en la FAQ de documentación del grupo Lilo (SGML/docbook). La instalación de las herramientas no es una tarea trivial, o sea, que si ves que este paso te supera, no le des más vueltas; el coordinador lo hará por ti al recibir el trabajo.

La entrega al repositorio

Pues vamos con el último paso: la entrega al repositorio. Esta fase es, sin duda, la más compleja, ya que es necesario conocer el funcionamiento de numerosas herramientas: svn, make, db2html, etc. Si queremos ser totalmente rigurosos sería incluso necesario disponer de un entorno para compilar paquetes de desarrollo GNOME. Todo esto no es, desde luego, una tarea trivial, por lo que si os véis superados nuevamente, dejad este tipo de tareas para los coordinadores. Tampoco quisiera desanimaros, a la postre es todo cuestión de remangarse. En las próximas secciones intentaré acercaros mis experiencias con las entregas.

Copiar el paquete del SVN

Para realizar la entrega de la documentación necesitamos en primer lugar obtener una copia del paquete al que pertenezca. Esta copia la obtenemos del repositorio CVS de Gnome utilizando los siguientes comandos:

 $     cd /gnome/cvs
 $     svo co http://svn.gnome.org/svn/gnome-applets/trunk gnome-applets

Como podrás observar, para esta primera operación, nos basta con una conexión anónima (no es necesaria una cuenta personal) que ni siquiera necesita clave de acceso.

Este comando utiliza la rama principal del paquete, conocida como TRUNK. En algunas ocasiones esta rama puede no ser la apropiada, y no deberían entregarse paquetes copiados de una rama en otra diferente (al menos sin estar seguro de lo que se hace).

Ficheros involucrados

Veamos ahora una lista de los ficheros que tendremos que manipular cuando realicemos una entrega:

 ./gnome-applets/ChangeLog
 ./gnome-applets/configure.in

 ./gnome-applets/whereami/ChangeLog
 ./gnome-applets/whereami/docs/Makefile.am

 ./gnome-applets/whereami/docs/es/Makefile.am
 
 ./gnome-applets/whereami/docs/es/figures
 ./gnome-applets/whereami/docs/es/figures/whereami_applet.png
 ./gnome-applets/whereami/docs/es/whereami.sgml
 ./gnome-applets/whereami/docs/es/whereami_applet.sgml
 ./gnome-applets/whereami/docs/es/license.sgml
 ./gnome-applets/whereami/docs/es/licencia-es.sgml
 ./gnome-applets/whereami/docs/es/licencia-nota-es.sgml
 ./gnome-applets/whereami/docs/es/authors.sgml
 ./gnome-applets/whereami/docs/es/topic.dat
 ./gnome-applets/whereami/docs/es/whereami_applet-es.omf

Como puede verse, tenemos los ya conocidos ficheros de la traducción y algunos ficheros adicionales. En los siguientes apartados iremos viendo cómo generar o modificar cada uno de ellos.

Ficheros de la traducción

Lo primero que debemos hacer es copiar los ficheros de la traducción es la estructura de directorios del paquete. Suponiendo que nuestro directorio de trabajo es /home/mbarreiro/traducciones/whereami, las comandos serían los siguientes

 $     cd /gnome/cvs/gnome-applets
 $     cd whereami/docs
 $     mkdir es
 $     cd es
 $     cp -rf /home/mbarreiro/traducciones/whereami/* .

Es importante asegurarnos de que no copiamos otros ficheros o directorios, como por ejemplo el directorio whereami que se genera al crear la documentación en formato html, o las copias de seguridad creadas al editar los ficheros (whereami.sgml~).

Con esto tendremos todos los ficheros en su lugar de destino, a falta del fichero Makefile.am. Veamos cómo conseguir y actualizar este fichero:

 $     cd /gnome/cvs/gnome-applets/whereami/docs/es 
 $     cp ../C/Makefile.am .

Como podéis ver, simplemente copiamos del directorio C, y después realizamos las siguientes modificaciones:

 '''gnome-applets/whereami/docs/es/Makefile.am'''

 figs = \
        figures/whereami_applet.png
 docname = whereami_applet
 lang = '''es'''
 omffile = whereami_applet-C.omf
 sgml_ents = whereami.sgml''' \
        license.sgml \
        licencia-es.sgml \
        licencia-nota-es.sgml \
        authors.sgml'''
 include $(top_srcdir)/sgmldocs.make
 dist-hook: app-dist-hook

Ficheros de la aplicación

Si la traducción es nueva, habrá que incluir el código de idioma para que se genere e instale la nueva documentación. Para ello modificaremos el fichero docs/Makefile.am:

 SUBDIRS = C '''es''' it

Para terminar debemos anotar los cambios que hemos realizado en el fichero ChangeLog, para que el resto de desarrolladores conozca los cambios que hemos realizado:

 2001-07-28  Manuel de Vega barreiro  &lt;mbarreiro@red.madritel.es&gt;

          New Spanish Translation
        * docs/es/*
        * docs/Makefile.am

Ficheros del paquete

A nivel de paquete debemos modificar el fichero configure.in, incorporando las siguientes modificaciones:

 ...
 AC_SUBST(CANVAS_PIXBUF_LIBS)
 ALL_LINGUAS="az ca cs da de el en_GB '''es''' et eu fi fr ga gl hu it ja ko lt nl nn no pl pt pt_BR ro ru sk sl sv tr uk wa zh_CN.GB2312 zh_TW.Big5"
 AM_GNOME_GETTEXT
 ...
 AC_OUTPUT([
 gnome-applets.spec
 Makefile
 macros/Makefile
 ...
 whereami/docs/it/Makefile
 '''whereami/docs/es/Makefile'''
 gtik/Makefile
 ...

Observa que el código de cada idioma se añade respetando el orden alfabético, ya que en caso contrario todo el mundo se volvería loco al introducir un nuevo idioma.

Como de costumbre, debemos reflejar todos los cambios en el ChangeLog, esta vez a nivel de paquete, para que el resto de desarrolladores conozca los cambios que hemos realizado:

  2001-07-28  Manuel de Vega barreiro  &lt;mbarreiro@red.madritel.es&gt;

        Whereami help Spanish translation
        * configure.in
        * whereami/docs/Makefile.am
        * whereami/docs/es/*

Los ficheros ChangeLog y configure.in sufren frecuentes cambios, por lo que conviene modificarlos justo antes de realizar la entrega.

Pruebas de compilación

Ésta es, por así decirlo, la prueba del nueve. Se trata de compilar el paquete con las modificaciones que hemos incorporado. El problema es que compilar paquetes sacados directamente del repositorio no es una tarea fácil. Esto se debe más a las dependencias cruzadas con otros paquetes y librerías, que al propio paquete.

Jugar a compilar e instalar paquetes en desarrollo es la forma mas fácil de conseguir un escritorio inutilizable. No lo hagas en un sistema en producción, ni en un ordenador del que dependa tu trabajo diario.

Dicho todo esto, veamos los comandos para compilar el paquete:

 $     cd /gnome/cvs/gnome-applets
 $     ./autogen.sh
 $     make

Como ves, nada del otro mundo; son los comandos habituales para instalar paquetes GNU.

Documentacion/Guias/TraduccionDeAyudas (última edición 2008-12-04 08:49:10 efectuada por anónimo)