.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PO4A-GETTEXTIZE 1p" .TH PO4A-GETTEXTIZE 1p "2022-07-15" "Herramientas de po4a" "Herramientas de po4a" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NOMBRE" .IX Header "NOMBRE" po4a\-gettextize \- Convierte un fichero original (y su traducción) a un fichero \s-1PO\s0 .SH "SINOPSIS" .IX Header "SINOPSIS" \&\fBpo4a\-gettextize\fR \fB\-f\fR \fIformatoE\fR \fB\-m\fR \fIoriginal.doc\fR [\fB\-l\fR \fI\s-1XX\s0.doc\fR] \fB\-p\fR \fI\s-1XX\s0.po\fR .PP (\fI\s-1XX\s0.po\fR es la salida, todos los otros son entrada) .SH "DESCRIPCIÓN" .IX Header "DESCRIPCIÓN" po4a (\s-1PO\s0 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. .PP El script \fBpo4a\-gettextize\fR se ocupa de la conversión de los ficheros de documentación a ficheros \s-1PO.\s0 Solamente lo necesita para configurar su proyecto de traducción con po4a, nada después. .PP Si comienza desde el comienzo, \fBpo4a\-gettextize\fR extraerá las cadenas traducibles desde la documentación y escribe un archivo \s-1POT.\s0 Si proporciona un archivo traducido existente anteriormente con el indicador \fB\-l\fR, \fBpo4a\-gettextize\fR intentará utilizar las traducciones que contiene dentro del fichero \s-1PO\s0 producido. Este proceso parece tedioso y manual, como explicaba en la Sección «Convertir una traducción manual a po4a» debajo. .PP Si el documento original contiene caracteres no \s-1ASCII,\s0 el fichero \s-1PO\s0 generado estará en \s-1UTF\-8.\s0 En otro caso (si el documento maestro está completamente en \s-1ASCII\s0), el \s-1PO\s0 generado utilizará la codificación de la entrada traducida del documento, o \s-1UTF\-8\s0 si no es proporcionado ningún documento traducido. .SH "OPCIONES" .IX Header "OPCIONES" .IP "\fB\-f\fR, \fB\-\-format\fR" 4 .IX Item "-f, --format" El formato de la documentación que desea tratar. Use la opción \fB\-\-help\-format\fR para ver la lista de los formatos disponibles. .IP "\fB\-m\fR, \fB\-\-master\fR" 4 .IX Item "-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. .IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4 .IX Item "-M, --master-charset" El juego de caracteres del fichero que contiene el documento a traducir. .IP "\fB\-l\fR, \fB\-\-localized\fR" 4 .IX Item "-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. .IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4 .IX Item "-L, --localized-charset" El juego de caracteres del fichero que contiene la versión localizada del documento. .IP "\fB\-p\fR, \fB\-\-po\fR" 4 .IX Item "-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. .IP "\fB\-o\fR, \fB\-\-option\fR" 4 .IX Item "-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'. .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Muestra un mensaje corto de ayuda. .IP "\fB\-\-help\-format\fR" 4 .IX Item "--help-format" Listado de formatos de documentación reconocidos por po4a. .Sp = item \fB\-k\fR \fB\-\-keep\-temps\fR .Sp Keep the temporary master and localized \s-1POT\s0 files built before merging. This can be useful to understand why these files get desynchronized, leading to gettextization problems .IP "\fB\-V\fR, \fB\-\-version\fR" 4 .IX Item "-V, --version" Muestra la versión del script y cierra. .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 .IX Item "-v, --verbose" Aumenta la cantidad de mensajes informativos del programa. .IP "\fB\-d\fR, \fB\-\-debug\fR" 4 .IX Item "-d, --debug" Devuelve por la salida información de depuración de fallos. .IP "\fB\-\-msgid\-bugs\-address\fR \fIcorreo\-e@direccion\fR" 4 .IX Item "--msgid-bugs-address correo-e@direccion" Define el destinatario de los informes de fallo en los msgid. Por omisión, los ficheros \s-1POT\s0 creados no tienen el campo «Report\-Msgid\-Bugs\-To». .IP "\fB\-\-copyright\-holder\fR \fIcadena\fR" 4 .IX Item "--copyright-holder cadena" Define el titula de los derechos de reproducción en la cabecera del \s-1POT.\s0 El valor predefinido es «Free Software Foundation, Inc.» .IP "\fB\-\-package\-name\fR \fIstring\fR" 4 .IX Item "--package-name string" Define el nombre del paquete en la cabecera del \s-1POT.\s0 El valor por omisión es «PACKAGE». .IP "\fB\-\-package\-version\fR \fIstring\fR" 4 .IX Item "--package-version string" Define la versión del paquete en la cabecera del \s-1POT.\s0 El valor por omisión es «VERSION». .SS "Convertir una traducción manual a po4a" .IX Subsection "Convertir una traducción manual a po4a" \&\fBpo4a\-gettextize\fR intentará extraer el contenido de cualquier fichero de traducción proporcionado, y utilizar este contenido como msgstr dentro del fichero \s-1PO\s0 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. .PP 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. .PP .Vb 1 \& 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 .Ve .PP \&\fBpo4a\-gettextize\fR 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. .PP 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 \fIfuzzy\fR 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. .PP 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 \fImaestro.doc\fR que fue utilizado para la traducción, y solamente actualice el archivo \s-1PO\s0 respecto al último fichero maestro una vez que la ‘gettextización’ sea lograda. .PP Si está de suficiente suerte para tener una coincidencia perfecta dentro de las estructuras del fichero, compilando un fichero \s-1PO\s0 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. .PP 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. .SS "Consejos y trucos para el proceso de gettextización" .IX Subsection "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 \fBdiff\fR\|(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?). .PP 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. \fBpo4a\-gettextize\fR 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 \s-1PO\s0 generado hasta el momento está volcado como \fIgettextization.failed.po\fR para más inspección. .PP Aquí hay algunos trucos para ayudarle en este proceso tedioso: .IP "\(bu" 4 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 \fBpo4a\fR\|(7)). .IP "\(bu" 4 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 \s-1PO,\s0 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 \s-1PO\s0 con el que comenzar. .IP "\(bu" 4 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 \s-1PO\s0 con el documento. .IP "\(bu" 4 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 ;) .IP "\(bu" 4 A veces el contenido del párrafo encaja, pero no sus tipos. Arreglar eso depende más bien del formato. En \s-1POD\s0 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 \s-1XML.\s0 .Sp De manera parecida, dos párrafos se podrían fusionar en un \s-1POD\s0 cuando la línea de separación contiene algunos espacios, o cuando no hay una línea de separación entre la línea \fB=item\fR y el contenido del elemento («item»). .IP "\(bu" 4 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 \fIgettextization.failed.po\fR, y repare el problema donde realmente está. .IP "\(bu" 4 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. .Sp 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 \s-1PO\s0 files would miss an entry (that would be reported as duplicate, with two references), the pairing would fail. .Sp Since po4a uses the entry type (\*(L"title\*(R" or \*(L"plain paragraph\*(R", 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. .Sp 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. .IP "\(bu" 4 As a final note, do not be too surprised if the first synchronization of your \s-1PO\s0 file takes a long time. This is because most of the msgid of the \s-1PO\s0 file resulting from the gettextization don't match exactly any element of the \s-1POT\s0 file built from the recent master files. This forces gettext to search for the closest one using a costly string proximity algorithm. .Sp Por ejemplo, el primer Bzpo4a\-updatepo> de la traducción española de la documentación de Perl (5.4 \s-1MB\s0 de archivos \s-1PO\s0) tomaron cerca de 48 horas (sí, dos días) mientras que los subsiguientes solamente toman una docena de segundos. .SH "VÉASE TAMBIÉN" .IX Header "VÉASE TAMBIÉN" \&\fBpo4a\fR\|(1), \fBpo4a\-normalize\fR\|(1), \fBpo4a\-translate\fR\|(1), \fBpo4a\-updatepo\fR\|(1), \fBpo4a\fR\|(7). .SH "AUTORES" .IX Header "AUTORES" .Vb 3 \& Denis Barbier \& Nicolas François \& Martin Quinson (mquinson#debian.org) .Ve .SH "TRADUCCION" .IX Header "TRADUCCION" .Vb 2 \& Jordi Vilalta \& Omar Campagne .Ve .SH "DERECHO DE COPIA Y LICENCIA" .IX Header "DERECHO DE COPIA Y LICENCIA" Copyright 2002\-2020 by \s-1SPI,\s0 inc. .PP Esto es software libre; puede redistribuirlo y/o modificarlo bajo las condiciones de la licencia \s-1GPL\s0 (consulte el fichero \s-1COPYING\s0).