NOMBRE

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

SINOPSIS

       po4a-gettextize -f formatoE -m original.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 se ocupa de la conversión de los ficheros de documentación a
       ficheros PO. Solamente lo necesita para configurar su proyecto de traducción con po4a,
       nada después.

       Si comienza desde el comienzo, po4a-gettextize extraerá las cadenas traducibles desde la
       documentación y escribe un archivo POT. Si proporciona un archivo traducido existente
       anteriormente con el indicador -l, po4a-gettextize intentará utilizar las traducciones que
       contiene dentro del fichero PO producido. Este proceso parece tedioso y manual, como
       explicaba en la Sección «Convertir una traducción manual a po4a» debajo.

       Si el documento original contiene caracteres no ASCII, el fichero PO generado estará en
       UTF-8. En otro caso (si el documento maestro está completamente en ASCII), el PO generado
       utilizará la codificación de la entrada traducida del documento, o UTF-8 si no es
       proporcionado ningún documento traducido.

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.

           = item -k --keep-temps

           Keep the temporary master and localized POT files built before merging. This can be
           useful to understand why these files get desynchronized, leading to gettextization
           problems

       -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 intentará extraer el contenido de cualquier fichero de traducción
       proporcionado, y utilizar este contenido como msgstr dentro del fichero PO producido.
       Advierta que este proceso es muy frágil: la enésima cadena del fichero traducido se toma
       como la traducción de la enésima cadena del original. Esto naturalmente no funcionará a no
       ser que ambos ficheros compartan la misma estructura.

       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.  Por ejemplo, si
       los ficheros tienen la siguiente estructura, 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 similar que un parágrafo nuevo fuera añadido al original, o que
       dos parágrafos originales fueran combinados a la vez dentro de 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
       detectada. Cuando esto ocurre, editaría manualmente los archivos (esto probablemente
       requiere que tenga alguna noción del idioma destino). Debe añadir párrafos simulados o
       quite algún contenido dentro de uno de los documentos (u ambos) para reparar las
       disparidades comunicadas, hasta que la estructura de albos documentos coincidan
       perfectamente. Algunos trucos se dan en la siguiente sección.

       Incluso cuando el documento es procesado correctamente, aún es posible haber disparidades
       no detectadas y errores silenciosos. Eso es por qué cualquier traducción asociada
       automáticamente por po4a-gettextize esté marcado como fuzzy para requerir una inspección
       manual por humanos. Uno tiene que comprobar que cada msgstr obtenido actualmente es la
       traducción del msgid asociado, y no la cadena anterior o posterior.

       Como puede ver, la clave aquí es tener la misma estructura exacta dentro del documento
       traducido y dentro del original. Lo mejor es hacer la ‘gettextización’ en la versión
       exacta de maestro.doc que fue utilizado para la traducción, y solamente actualice el
       archivo PO respecto al último fichero maestro una vez que la ‘gettextización’ sea lograda.

       Si está de suficiente suerte para tener una coincidencia perfecta dentro de las
       estructuras del fichero, compilando un fichero PO correcto es una materia de segundos. Por
       otra parte pronto entenderá por qué este proceso tiene tal nombre feo :) Pero recuerde que
       esta faena funciona es el precio de pagar para obtener el confort de po4a después de
       todos. Una vez convertido, la sincronización entre documentos maestros y las traducciones
       siempre serán completamente automáticos.

       Aunque las cosas vayan mal, gettextization a menudo sigue siendo más rápido que traducirlo
       todo de nuevo. Yo hice la gettextización de la traducción al francés existente de la
       documentación de Perl en un día, a pesar que la estructura de muchos documentos fueron
       desincronizados. Eso fue más que dos megabytes de texto original (2 millones de
       caractres): reiniciando la traducción desde el principio hubiera requerido varios meses de
       trabajo.

   Consejos y trucos para el proceso de gettextización
       The gettextization stops as soon as a desynchronization is detected. In theory, it should
       probably be possible resynchronize the gettextization later in the documents using e.g.
       the same algorithm than the diff(1) utility. But a manual intervention would still be
       mandatory to manually match the elements that couldn't be automatically matched,
       explaining why automatic resynchronization is not implemented (yet?).

       Cuando esto ocurra, el juego completo baja para el alineamiento de esta estructura de
       estos ficheros complejos a través de las ediciones del manual. po4a-gettextize es mejor
       que verborrea sobre qué vino mal cuando ocurrió. Esto comunica las cadenas que no encajan,
       su posición en el texto, y el tipo de cada una. Además, el fichero PO generado hasta el
       momento está volcado como gettextization.failed.po para más inspección.

       Aquí hay algunos trucos para ayudarle en este proceso tedioso:

       •   Retire todos el contenido adicional de la traducción, como la sección proporcionado
           reconocimientos a los traductores. Puede añadirlos de vuelta en po4a a pesar de todo,
           utilizando un addenda (vea po4a(7)).

       •   Si necesita editar los ficheros para alinear sus estructuras, preferiría editar la
           traducción si es posible. Ciertamente, si los cambios al original son demasiado
           intrusismo, las versiones anteriores y nuevas no serán coincidentes durante la
           actualización del PO, y la traducción correspondiente será volcada completamente. Pero
           no dude también editar el documento original si se requiere: 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 comunicar al autor. Arreglarlo en su traducción solo las soluciona a
           una parte de la comunidad. Y además, es imposible hacerlo así cuando se usa po4a ;)

       •   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 asincronía parece impar porque la traducción está empareja con
           un párrafo original equivocado. Éste es un signo de que el problema no detectado
           anterior en el proceso. Busque el punto de desincronización actual inspeccionando
           gettextization.failed.po, y repare el problema donde realmente está.

       •   In some case, po4a adds a space at the end of either the original or the translated
           strings. This is because every string must be deduplicated during the gettextize
           process. Imagine that a string appearing several times unmodified in the original, but
           is translated in differing way, or that different paragraphs are translated in the
           exact same way.

           Without deduplication, such case would break the gettexization algorithm, as it is a
           simple one to one pairing between the msgids of both the master and the localized
           files. Since one of the PO files would miss an entry (that would be reported as
           duplicate, with two references), the pairing would fail.

           Since po4a uses the entry type ("title" or "plain paragraph", etc) to detect whether
           the parsing streams got desynchronized, similar issues could occur if two identical
           entries (same content but differing type) of the master file are translated in the
           exact same way in the localized file. po4a would detect a fake desyncronization in
           such case.

           In most cases, the extra space added by po4a to deduplicate the strings has no impact
           on the formatting. Strings are fuzzied anyway, and msgmerge will probably match the
           strings accordingly afterward.

       •   As a final note, do not be too surprised if the first synchronization of your PO file
           takes a long time. This is because most of the msgid of the PO file resulting from the
           gettextization don't match exactly any element of the POT file built from the recent
           master files. This forces gettext to search for the closest one using a costly string
           proximity algorithm.

           Por ejemplo, el primer Bzpo4a-updatepo> de la traducción española de la documentación
           de Perl (5.4 MB de archivos PO) tomaron cerca de 48 horas (sí, dos días) mientras que
           los subsiguientes solamente toman una docena de segundos.

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

       Copyright 2002-2020 by SPI, inc.

       Esto es software libre; puede redistribuirlo y/o modificarlo bajo las condiciones de la
       licencia GPL (consulte el fichero COPYING).