Traducción de la documentación

La traducción de la documentación se realiza del mismo modo que la traducción de aplicaciones. El coordinador del equipo se encarga de generar los correspondientes archivos en formato DocBook y de subirlos al 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:

• Sería recomendable que el traductor de una determinada aplicación se hiciera cargo también de la traducción de su documentación. De esta forma se podrá garantizar el uso de una terminología común y la coincidencia entre los textos que se muestran en la interfaz del programa y en su documentación.
• Si no se puede cumplir la recomendación anterior, el encargado de la documentación debería consultar la traducción de la interfaz de la correspondiente aplicación para usar la misma terminología. Puede conseguir este objetivo descargando también los archivos PO de la interfaz (aunque no tenga asignada su traducción) para poder consultarlos de una forma cómoda. También es posible que deba ponerse en contacto con el encargado de traducir la interfaz para mantener la coherencia de ambas traducciones.
• Si un archivo PO no está completamente traducido (es decir, si contiene alguna entrada dudosa o sin traducir), no se podrá generar su correspondiente archivo en formato DocBook.
• Existen documentos que por su tamaño se han dividido en múltiples archivos PO. Por ejemplo, las FAQ. Para que se pueda generar la documentación correspondiente, deben estar completamente traducidos todos los archivos PO de dicha documentació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>
  

Entidades

Las 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 escribirlas exactamente como están en el mensaje original y no traducirlas. El olvido del punto y coma genera errores en la traducción.

Como excepción, algunas de estas entidades solo sirven ahorrar trabajo al traductor, aunque cuando se sustituyen por su texto equivalente se muestran con un formato de texto que puede parecer inadecuado. Es el caso de las entidades ⪚ (que se sustituye por por ejemplo), &ie; (que se sustituye por es decir) y &etc; (que se sustituye por etc., con el punto incluido). El problema es que el texto resultante aparece en mayúsculas (como si fuesen siglas), algo que no es estético. Por ello, se recomienda encarecidamente sustituir estas tres entidades por sus textos traducidos, usando mayúscula inicial si aparecen al principio de una frase (excepto etc., evidentemente):

• ⪚ se debería sustituir por por ejemplo (con mayúscula inicial cuando corresponda).
• &ie; se debería sustituir por es decir (con mayúscula inicial cuando corresponda).
• &etc; se debería sustituir por etc. (terminado en punto) o por etcétera.

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:

   /ruta/a/scripty/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:

  /ruta/a/scripty/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 del programa Kalzium, habrá que ejecutar:

  /ruta/a/scripty/update_xml es kdeedu kalzium

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 documentation (este último directorio se descarga usando Scripty), ambas en la misma carpeta de nuestra copia local del repositorio. Luego abrimos una consola en dicha carpeta y ejecutamos la orden:

  /ruta/a/scripty/update_xml es kdeadmin

que actualizará 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 meinproc5 (que forma parte del paquete kdoctools de su distribución) sobre los archivos DocBook 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.