PO4A-GETTEXTIZE.1P

Section: User Contributed Perl Documentation (1)
Updated: 2024-06-17
Index Return to Main Contents

NOMBRE

po4a-gettextize - Convierte un fichero original (y su traducción) a un fichero PO

SINOPSIS

po4a-gettextize -f fmt -m master.doc -l XX.doc -p XX.po

(XX.po es la salida, todos los otros son entrada)

DESCRIPCIÓN

po4a (PO para cualquier cosa) facilita el mantenimiento de la traducción de documentación utilizando las herramientas clásicas de gettext. La característica principal de po4a es que desacopla la traducción del contenido de la estructura del documento. Consulte la página po4a (7) para obtener una breve introducción a este proyecto.

El script po4a-gettextize le ayuda a convertir sus traducciones ya existentes a un flujo de trabajo basado en po4a. Esto solo debe hacerse una vez para salvar una traducción existente al convertir a po4a, no de forma regular tras la conversión de su proyecto. Este tedioso proceso se explica en detalle en la sección 'Convertir una traducción manual a po4a' más abajo.

Debe proporcionar tanto un archivo maestro (por ejemplo, la fuente en inglés) como un fichero traducido existente (por ejemplo, un intento de traducción anterior sin po4a). Si proporciona más de un archivo maestro o de traducción, se usarán en secuencia, pero puede ser más fácil gettextizar cada página o capítulo por separado y luego usar msgmerge para fusionar todos los archivos PO producidos. Como desee.

Si el documento original contiene caracteres no ASCII, el fichero PO generado estará en UTF-8. Si el documento maestro está completamente en ASCII, el PO generado utilizará la codificación del documento traducido de entrada.

OPCIONES

-f, --format: El formato de la documentación que desea tratar. Use la opción --help-format para ver la lista de los formatos disponibles.
-m, --master: El fichero que contiene el documento original o principal a traducir. Puede usar esta opción varias veces si desea gettextizar varios documentos.
-M, --master-charset: El juego de caracteres del fichero que contiene el documento a traducir.
-l, --localized: El fichero que contiene el documento localizado (traducido). Si introdujo varios documentos originales, puede que desee introducir varios documentos localizados usando esta opción más de una vez.
-L, --localized-charset: El juego de caracteres del fichero que contiene la versión localizada del documento.
-p, --po: El fichero dónde se debería escribir el catálogo de mensajes. Si no se proporciona, el catálogo de mensajes se escribirá por la salida estándar.
-o, --option: Opción(es) adicionales a introducir a la extensión del formato. Consulte la documentación de cada extensión para más información acerca de las opciones aceptadas y su significado. Por ejemplo, puede pasar '-o tablecells' al intérprete AsciiDoc, mientras que el intérprete de texto aceptaría '-o tabs=split'.
-h, --help: Muestra un mensaje corto de ayuda.
--help-format: Listado de formatos de documentación reconocidos por po4a.
-k --keep-temps: Conserve los archivos POT localizados originales y temporales generados antes de la fusión. Esto puede ser útil para comprender por qué estos archivos no están sincronizados, lo que genera problemas de obtención de texto.
-V, --version: Muestra la versión del script y cierra.
-v, --verbose: Aumenta la cantidad de mensajes informativos del programa.
-d, --debug: Devuelve por la salida información de depuración de fallos.
--msgid-bugs-address correo-e@direccion: Define el destinatario de los informes de fallo en los msgid. Por omisión, los ficheros POT creados no tienen el campo «Report-Msgid-Bugs-To».
--copyright-holder cadena: Define el titula de los derechos de reproducción en la cabecera del POT. El valor predefinido es «Free Software Foundation, Inc.»
--package-name string: Define el nombre del paquete en la cabecera del POT. El valor por omisión es «PACKAGE».
--package-version string: Define la versión del paquete en la cabecera del POT. El valor por omisión es «VERSION».

Convertir una traducción manual a po4a

po4a-gettextize sincronizará los archivos maestro y localizado para extraer su contenido a un archivo PO. El contenido del archivo maestro está en msgid, mientras que el contenido del archivo localizado está en msgtr. Este proceso es algo frágil: la enésima cadena del archivo traducido se toma como la traducción de la enésima cadena del original.

La gettextización funciona mejor si consigue recuperar la versión exacta del documento original que se utilizó para la traducción. Aun así, si el traductor original modificó la estructura de los archivos, es posible que tenga que manipular tanto el archivo maestro como el localizado para alinear su estructura, por lo que se recomienda trabajar con copias de los archivos.

Internamente, cada intérprete po4a comunica el tipo sintáctico de cada cadena extraída. Esto es como la desincronización es detectada durante la gettextización. En el ejemplo mostrado abajo, es muy poco probable que la cuarta cadena de la traducción (de tipo 'capítulo') sea la traducción de la cuarta cadena del original (de tipo 'párrafo'). Es más probable que un parágrafo nuevo fuera añadido al original, o que dos parágrafos originales fueran combinados en la traducción.

    Original         Traducción

  capítulo           capítulo
    párrafo            párrafo
    párrafo            párrafo
    párrafo          capítulo
  capítulo             párrafo
    párrafo            párrafo

po4a-gettextize diagnosticará detalladamente cualquier desincronización de estructura. Cuando esto ocurre, debería editar manualmente los archivos para añadir párrafos simulados o retirar algún contenido aquí y allá hasta que la estructura de ambos documentos coincidan. Se dan algunos trucos en la siguiente sección para salvar la mayor parte posible de la traducción al hacerlo.

Si tiene la fortuna de tener una coincidencia perfecta entre las estructuras de los archivos sin hacer nada, crear un fichero PO correcto es una cuestión de segundos. Si no, pronto entenderá por qué este proceso tiene un nombre tan feo :) Aun así, la gettextización sigue siendo más rápida que traducirlo todo de nuevo. Yo gettexticé la traducción al francés de toda la documentación Perl en un día a pesar de los l<muchos> problemas de sincronización. Dada la cantidad de texto (2MB de texto original), reiniciar la traducción sin salvar primero las traducciones antiguas hubiera requerido varios meses de trabajo. Además, este trabajo pesado es el precio que hay que pagar para obtener el confort de po4a. Una vez hecha la conversión, la sincronización entre documentos maestros y las traducciones siempre será completamente automática.

Tras una gettextización correcta, los documentos producidos deben comprobarse manualmente para detectar disparidades y errores silenciosos, como se explica a continuación.

Consejos y trucos para el proceso de gettextización

La gettextización se detiene en cuanto se detecta una desincronización. Cuando esto ocurre, es necesario editar los archivos tanto como sea necesario para realinear sus estructuras. po4a-gettextize es bastante verboso cuando las cosas van mal. Informa de las cadenas que no coinciden, sus posiciones en el texto, y el tipo de cada una de ellas. Además, el archivo PO generado hasta el momento se vuelca como gettextization.failed.po para su posterior inspección.

Aquí hay algunos trucos para ayudarle en este proceso tedioso y asegurarse de que salva lo máximo posible de la traducción anterior:

•: Eliminar todo el contenido extra de las traducciones, como la sección que da créditos a los traductores. Deberán añadirse por separado a po4a como apéndices (véase po4a(7)).
•: Si necesita editar los ficheros para alinear sus estructuras, es preferible editar la traducción si es posible. Ciertamente, si los cambios al original son demasiado intrusivos, las versiones antigua y nueva no serán coincidentes durante la primera ejecución de po4a después de la gettextización (vea más abajo). Cualquier traducción que no coincida será descartada de todas formas. Dicho esto, es recomendable editar el documento original si es demasiado difícil conseguir que la gettextización proceda de otra forma, incluso si esto significa que un párrafo de la traducción se descarte. Lo importante es obtener un fichero PO con el que comenzar.
•: No dude en eliminar cualquier contenido original que no existiese dentro de la versión traducida. Este contenido será reintroducido automáticamente después, cuando sincronice el fichero PO con el documento.
•: Probablemente debería informar al autor original de cualquier cambio estructural dentro de la traducción que parezca justificado. Si hay problemas con el documento original debería comunicarlo al autor. Arreglarlas en su traducción solo las soluciona a una parte de la comunidad. Y además, es imposible hacerlo así cuando se usa po4a ;) Pero probablemente quieras esperar al final de la conversión a po4a antes de cambiar los archivos originales.
•: A veces el contenido del párrafo encaja, pero no sus tipos. Arreglar eso depende más bien del formato. En POD y man, a menudo es culpa de que una de las líneas empieza con un espacio y la otra no. En estos formatos, este párrafo no se podría justificar y su tipo cambiaría. Simplemente elimine el espacio y ya está. También puede tratarse de un error tipográfico en el nombre de la etiqueta en XML.
De manera parecida, dos párrafos se podrían fusionar en un POD cuando la línea de separación contiene algunos espacios, o cuando no hay una línea de separación entre la línea =item y el contenido del elemento («item»).
•: A veces, el mensaje de desincronización parece raro porque la traducción está emparejada con el párrafo original equivocado. Esto indica que hay un problema no detectado anteriormente en el proceso. Busque el punto de desincronización actual inspeccionando el archivo gettextization.failed.po, y repare el problema donde realmente está.
•: Otros problemas pueden provenir de cadenas duplicadas en el original o en la traducción. Las cadenas duplicadas se fusionan en archivos PO, con dos referencias. Esto constituye una dificultad para el algoritmo de gettextización, que es un simple emparejamiento uno a uno entre las msgids de los archivos maestro y localizado. Sin embargo, se cree que las versiones recientes de po4a tratan adecuadamente las cadenas duplicadas, por lo que debería informar de cualquier problema restante que pueda encontrar.

Revisión de los archivos producidos por po4a-gettextize

Cualquier archivo producido por po4a-gettextize debe ser revisado manualmente, incluso cuando el script termina con éxito. Debería hojear el fichero PO, asegurándose de que el msgid y el msgstr coinciden realmente. No es necesario asegurarse todavía de que la traducción es perfectamente correcta, ya que todas las entradas se marcan como fuzzies de todas formas. Solo necesita comprobar los problemas obvios de concordancia, porque las traducciones mal emparejadas serán desechadas en pasos posteriores, y usted quiere salvarlas.

Afortunadamente, este paso no requiere dominar las lenguas de destino, ya que solo se trata de reconocer elementos similares en cada msgid y su correspondiente msgstr. Como hablante de francés, inglés y algo de alemán, puedo hacer esto al menos para todas las lenguas europeas, aunque no sepa decir ni una palabra en la mayoría de ellas. A veces consigo detectar problemas de concordancia en lenguas no latinas fijándome en la longitud de las cadenas, las estructuras de las frases (¿coincide la cantidad de signos de interrogación?) y otras pistas, pero prefiero que sea otra persona quien revise esas lenguas.

Si detecta un desajuste, edite los archivos original y traducido como si po4a-gettextize informara de un error, e inténtelo de nuevo. Una vez que tenga un archivo PO decente para su traducción anterior, haga una copia de seguridad hasta que consiga que po4a funcione correctamente.

Ejecutar po4a por primera vez

La forma más fácil de configurar po4a es escribir un fichero de configuración po4a.conf, y usar el programa integrado po4a (po4a-updatepo y po4a-translate están obsoletos). Consulte la sección "ARCHIVO DE CONFIGURACIÓN" de la documentación de po4a(1) para obtener más información.

Cuando po4a se ejecuta por primera vez, se utilizará la versión actual de los documentos maestros para actualizar los archivos PO que contienen las traducciones antiguas que rescató mediante la gettextización. Esto puede llevar bastante tiempo, porque muchos de los msgids de la gettextización no coinciden exactamente con los elementos del fichero POT construido a partir de los archivos maestros recientes. Esto obliga a gettext a buscar el más cercano utilizando un costoso algoritmo de proximidad de cadenas. Por ejemplo, la primera ejecución sobre la traducción al francés de la documentación de Perl (fichero PO de 5,5 MB) tardó unas 48 horas (sí, dos días) mientras que las siguientes sólo tardan segundos.

Pasar sus traducciones a producción

Tras esta primera ejecución, los archivos PO están listos para ser revisados por los traductores. Todas las entradas fueron marcadas como fuzzies en el archivo PO por po4a-gettextization, forzando su cuidadosa revisión antes de su uso. Los traductores deben tomar cada entrada para verificar que la traducción rescatada coincide realmente con el texto original actual, actualizar la traducción según sea necesario y eliminar los marcadores fuzzy.

Una vez que se hayan eliminado suficientes marcadores fuzzy, po4a empezará a generar los archivos de traducción en disco, y ya estará listo para pasar su flujo de trabajo de traducción a producción. Algunos proyectos encuentran útil usar Weblate para coordinar a traductores y mantenedores, pero eso está fuera del alcance de po4a.

VÉASE TAMBIÉN

po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

AUTORES

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

TRADUCCION

 Jordi Vilalta <jvprat@gmail.com>
 Omar Campagne <ocampagne@gmail.com>

DERECHO DE COPIA Y LICENCIA

Este programa es software libre; puede redistribuirlo y/o modificarlo bajo los términos de la GPL v2.0 o posterior (consulte el archivo COPYING).

Index

Convertir una traducción manual a po4a
Revisión de los archivos producidos por po4a-gettextize
Ejecutar po4a por primera vez
Pasar sus traducciones a producción

VÉASE TAMBIÉN

AUTORES

TRADUCCION

DERECHO DE COPIA Y LICENCIA

This document was created by using the manual pages.
Time: 20:30:45 GMT, June 17, 2024

po4av0.73