Traducción de la documentación

La traducción de la documentación se realiza del mismo modo que la traducción de archivos de mensajes de aplicaciones. Un proceso automático genera los archivos docbook en el repositorio a partir de los archivos PO traducidos.

Detalles importantes

Se deben observar algunos detalles importantes durante el proceso de traducción de la documentación:

• Si un archivo PO no está totalmente traducido (es decir, si contiene alguna entrada dudosa o sin traducir) y se deposita en el repositorio, el procedimiento automático no generará el archivo docbook correspondiente.
• Existen documentos que por su tamaño se han dividido en múltiples archivos PO. Por ejemplo, las FAQ. Para que el procedimiento automático genere la documentación correspondiente, deben estar traducidos todos los archivos PO de dicha documentación.
• Aquellas palabras que aparecen entre un signo & y un punto y coma (como &application;) se denominan entidades, y corresponden habitualmente a nombres de aplicaciones definidas en un archivo general, por lo que es muy importante copiarlas exactamente desde el mensaje original y no traducirlas. El olvido del punto y coma genera errores en la traducción.

Títulos de crédito

Los mensajes de la documentación que hacen referencia a nuestro trabajo como traductores son dos:

• La cadena ROLES_OF_TRANSLATORS, que traduciremos con el siguiente formato fijo:
  

      <othercredit role=\"translator\">
      <firstname>Fulanito</firstname>
      <surname>Pérez</surname>
      <affiliation>
      <address>
      <email>fulanito@miisp.com</email>
      </address>
      </affiliation>
      <contrib>Traductor</contrib>
      </othercredit>
  

• La cadena CREDIT_FOR_TRANSLATORS, algo más flexible (aunque no mucho), que traduciremos así:
  

      <para>Traducido por Fulanito Pérez
      <email>fulanito@miisp.com</email>.</para>
  

Si el archivo que estamos traduciendo ya contuviera títulos de crédito de traductores anteriores, añadiremos un bloque idéntico con nuestros datos delante del existente. En el caso de la cadena CREDIT_FOR_TRANSLATORS podemos optar por dos soluciones:

• Añadir un bloque con nuestros datos, adaptando el texto. Por ejemplo:
  

      <para>Traducción hasta la versión X por 
      Fulanito Pérez <email>fulanito@miisp.com</
      email>.</para>
      <para>Traducción a partir de la versión Y por
      Menganito López <email>menganito@miisp.com</
      email>.</para>
  

• O bien ampliar el texto existente para que incluya también nuestros datos. Por ejemplo:
  

      <para>Traducido por por Fulanito Pérez
      <email>fulanito@miisp.com</email> hasta la 
      versión X, y por Menganito López
      <email>menganito@miisp.com</email> a partir
      de la versión Y.</para>
  

Verificando nuestro trabajo

Tras concluir la traducción y realizar las mismas validaciones que para el caso de las aplicaciones, se puede comprobar que nuestro trabajo es correcto. Para ello es necesario ejecutar (desde la correspondiente carpeta l10n) el procedimiento:

   scripts/update_xml es

Esta orden se encuentra situada en la carpeta scripts (por lo que será necesario disponer de ella en nuestra copia local del repositorio, al igual que de las carpetas es y templates).

También es posible generar la documentación de un solo paquete. Por ejemplo, para generar la documentación del paquete kdeedu, habrá que ejecutar:

  scripts/update_xml es kdeedu

Incluso es posible generar la documentación de un único programa perteneciente a un paquete. Por ejemplo, para generar la documentación de Kalzium, habrá que ejecutar:

  scripts/update_xml es kalzium

Hay que tener en cuenta que update_xml solo funciona bien si se ha instalado KDE 2.2 o superior. Este procedimiento no solo comprueba la validez de los archivos sino que también genera los correspondientes archivos docbook ya traducidos.

A modo de ejemplo, para generar y comprobar la documentación de kdeadmin es necesario tener una copia de es/docmessages/kdeadmin y de scripts, ambas en la misma carpeta de nuestra copia local del repositorio. Luego abrimos una consola en dicha carpeta y ejecutamos la orden:

  scripts/update_xml es kdeadmin

que descargará del repositorio la correspondiente carpeta documentation/kdeadmin, y generará los correspondientes mensajes de error, si los hubiera. En la mayor parte de los casos, estos mensajes son autoexplicativos y permiten identificar el error y corregirlo. La nueva documentación será generada en la carpeta l10n/es/docs/kdeadmin.

A continuación se puede ejecutar meinproc sobre los archivos docbook (también se puede usar el comando kdb2html en su lugar) y comprobar con un navegador en la carpeta HTML los archivos html que se han generado. Lee el texto que has traducido, y en el caso de que encuentres errores, corrígelos en el archivo PO original. Después tendrás que repetir el proceso para generar los archivos docbook y html otra vez.

Cuando estés a gusto con la traducción, envíasela al coordinador para que la suba al repositorio y envía un mensaje a la lista de correo de KDE-ES para que el resto sepa que la traducción ya está lista.