Provided by: po4a_0.57-2_all 
NOMBRE
po4a - Actualiza los ficheros PO y los documentos traducidos a la vez
SINOPSIS
po4a [opciones] fichero_de_configuración
DESCRIPCIÓN
El objetivo del proyecto po4a («PO for anything», PO para todo) es facilitar la traducción (y más
interesante, el mantenimiento de las traducciones) usando las herramientas de gettext en ámbitos dónde no
previstos, como la documentación.
El programa po4a es útil cuando no desea invocar po4a-gettextize(1), po4a-updatepo(1), y
po4a-translate(1) a través de complejos ficheros «Makefile» cuando tiene varios ficheros a traducir,
diferentes formatos o necesita especificar diferentes opciones para cada documento.
Tabla de contenidos
Este documento está organizado de la siguiente forma:
DESCRIPCIÓN
INTRODUCCIÓN
SINTAXIS DEL FICHERO DE CONFIGURACIÓN
Especificar las plantillas de idiomas
Especificar las rutas a las entradas del traductor
Detección automática de las rutas e idiomas
Especificar los documentos a traducir
Especificar las opciones para los módulos
Especificar un alias
Modo dividido
OPCIONES
EJEMPLO
DEFICIENCIAS
VÉASE TAMBIÉN
AUTORES
DERECHO DE COPIA Y LICENCIA
INTRODUCCIÓN
El programa po4a se encarga de actualizar los ficheros PO (para sincronizarlos con los documentos
originales) y los documentos traducidos (para sincronizarlos con los ficheros PO). El objetivo es
simplificar el uso de po4a sin tener que recordar las opciones de línea de órdenes.
También le permite mezclar documentos en diferentes formatos en un mismo fichero POT, de manera que pueda
tener un sólo fichero por proyecto.
Este comportamiento se puede imitar con las otras herramientas del paquete po4a (por ejemplo con ficheros
«Makefile»), pero es bastante difícil y agotador el tener que rehacer los mismos ficheros «Makefile» para
cada proyecto que usa po4a.
El flujo de datos se puede resumir de la siguiente manera. Todo cambio al documento original quedará
reflejado en los ficheros PO, y todo cambio en los ficheros PO (manual o causado por el paso anterior)
quedará reflejado en los documentos traducidos.
Caso normal sin especificar pot_in:
<- ficheros de origen ->|<--------- resultados del proceso --------------->
apéndice ----------------------------------+
|
documento original -------+-------------+ |
V +--+--> traducciones
ficheros PO antiguos -----+--> ficheros PO actualizados +
^ |
| V
+<..........................+
(Los ficheros PO actualizados se copian
manualmente al origen de la siguiente
publicación, mientras se actualizan
manualmente los contenidos de traducción.)
Caso especial sin especificar pot_in:
<- ficheros de origen ->|<--------- resultados del proceso ----------------->
documento original --+-----------------------+
: |
externo : filtrado |
filtrando ========X..> original |
programa documento |
| |
V +--> traducciones
ficheros PO antiguos --+> ficheros PO actualizados +
^ |
| V
+<..........................+
(Los ficheros PO actualizados se copian
manualmente al origen de la siguiente
publicación mientras si copian
manualmente los contenidos de traducción.)
No se puede invertir el flujo de datos con esta herramienta, y el contenido de los ficheros PO
sobreescribirá los cambios en las traducciones. De hecho, no puede usar esta herramienta para convertir
traducciones existentes al sistema de po4a. Para ello, consulte po4a-gettextize(1).
SINTAXIS DEL FICHERO DE CONFIGURACIÓN
El argumento (obligatorio) es la ruta al fichero de configuración a usar. Su sintaxis intenta ser simple
y parecida a la de los ficheros de configuración usados por los proyectos intl-tools.
Los comentarios en estos ficheros se indican con el carácter «#». Comenta todo hasta el final de línea.
Las líneas se pueden continuar escapando el final de línea. Todas las líneas con contenido deben empezar
con una orden [], seguida por sus argumentos. (Suena difícil dicho así, pero es más bien fácil, espero
;).
Especificar las plantillas de idiomas
Nota: Recomendamos usar [po_directory] en lugar de [po4a_langs] y [po4a_paths]. Consulte la sección
Detección automática de las rutas e idiomas.
Ésta es una orden opcional que puede simplificar todo el fichero de configuración, y lo hará más
escalable. Debe especificar una lista de los idiomas a los que desee traducir los documentos. Es así de
simple:
[po4a_langs] fr de
Esto le permitirá expandir $lang a todos los idiomas especificados en el resto del fichero de
configuración.
Especificar las rutas a las entradas del traductor
Nota: Recomendamos usar [po_directory] en lugar de [po4a_langs] y [po4a_paths]. Consulte la sección
Detección automática de las rutas e idiomas.
Primero debe especificar la ubicación de los ficheros de entrada del traductor (es decir, los ficheros
que utilizan los traductores para hacer su trabajo). Puede hacer esto con la siguiente línea:
[po4a_paths] doc/l10n/project.doc.pot \
fr:doc/l10n/fr.po de:doc/l10n/de.po
Por ello, la orden es [po4a_paths]. El primer argumento es la ruta del fichero POT a usar. Todos los
argumentos posteriores tienen la siguiente forma, que se explica por si sola:
<idioma>:<ruta al fichero PO de este idioma>
Si ha definido la plantilla de idiomas, puede reescribir la linea anterior de la siguiente forma:
[po4a_paths] doc/l10n/proyecto.doc.pot $lang:doc/l10n/$lang.po
También puede usar $master para referirse al nombre de fichero del documento. En este caso po4a usará un
modo dividido: se creará un POT y un PO (por cada idioma) por cada documento especificado en el fichero
de configuración de po4a. Consulte la sección Modo dividido («Split Mode»).
[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
Detección automática de las rutas e idiomas
Puede usar otra orden para especificar el nombre del directorio donde se ubican los ficheros POT y PO. Si
se usa, po4a detectará el fichero POT como el único fichero *.pot en el directorio especificado. po4a
usará también la lista de ficheros *.po para definir la lista de idiomas (eliminando la extensión). Estos
idiomas se usarán como sustitución de la variable $lang en el resto del fichero de configuración.
No debería usar esta orden en combinación con las órdenes [po4a_langs] o [po4a_paths].
Al usar esta orden, tiene que crear un fichero POT vacío al ejecutar po4a por primera vez para así dar a
conocer el nombre del fichero POT.
[po_directory] po4a/po/
Especificar los documentos a traducir
Naturalmente, debe especificar qué documentos están traducidos, su formato, y dónde guardar sus
traducciones. Se puede hacer con líneas como las siguientes:
[type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
de:doc/de/mein_kram.sgml
[type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
add_fr:doc/l10n/script.fr.add
[type: docbook] doc/script.xml fr:doc/fr/script.xml \
de:doc/de/script.xml \
pot_in:doc/script.filtered.xml
Esto también se debería explicar por si mismo. Tenga en cuenta que en el segundo caso,
doc/l10n/script.fr.add es un apéndice a («addenda») añadir a la versión francesa del documento. Consulte
po4a(7) para más información sobre los apéndices.
Más formalmente, el formato es:
[type: <formato>] <doc_original> (<idioma>:<doc_traducido>)*\
pot_in:<doc_original_filtrado>)? \
(add_<idioma>:<argumento>*<ruta_al_apéndice>)*
Si se especifica pot_in, se utiliza el doc_original_filtrado para crear el fichero POT en lugar de
doc_original. Esta funcionalidad permite al usuario crear formas flexibles de omitir contenidos que no
se deben incluir en los ficheros PO. Se pueden utilizar herramientas como el preprocesador C (cpp) o la
herramienta de transformación XSL (p.ej., xsltproc) para crear el programa de filtrado externo e
invocarlo antes de invocar po4a.
De no existir argumentos, ruta_al_apéndice es la ruta a un apéndice. Los argumentos son
? Incluye ruta_al_apéndice si el fichero sí existe, y no hace nada de lo contrario.
@ ruta_al_apéndice no es un apéndice normal, sino un fichero que contiene una lista de apéndices, uno por
línea. Cada apéndice puede ir precedido de argumentos.
! Si ruta_al_apéndice se descarta, no se cargará, independientemente de cualquier especificación
adicional referida al apéndice.
Si ha definido la plantilla de idiomas, puede reescribir la linea anterior de la siguiente forma:
[type: pod] script $lang:doc/$lang/script.1 \
add_fr:doc/l10n/script.fr.add
Si todos los idiomas tuviesen apéndices con rutas similares, también podría escribir algo así.
[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add
Especificar las opciones para los módulos
po4a acepta opciones que se introducirán al módulo. Estas opciones son específicas a cada módulo y se
definen con la opción -o.
Si precisa de una opción en particular para uno de los documentos que desea traducir, también puede
especificarla en el fichero de configuración. Las opciones se introducen con la palabra clave opt. Debe
entrecomillar con comillas dobles el argumento de la palabra clave opt si éste contiene un espacio (por
ejemplo, si especifica varias opciones, o una opción con un argumento). Puede también especificar
opciones qué solo afectarán a un idioma en particular mediante la palabra clave opt_lang.
Este es un ejemplo:
[type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v Los argumentos pueden contener espacios si usa
comillas simples o unas comillas dobles con un escape:
[po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"
Si desea especificar las mismas opciones para varios documentos, puede que quiera usar un alias (consulte
a continuación la sección Especificar un alias).
También puede configurar opciones para todos los documentos especificados en el fichero de configuración:
[options] opt:"..." opt_fr:"..."
Especificar un alias
Si tiene que especificar las mismas opciones para varios ficheros, puede que le interese definir un alias
de módulo. Puede hacer esto de la siguiente forma:
[po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"
Esto define un alias de módulo llamado test, basado en el módulo man, y en el que -k 21 afecta a todos
los idiomas, con -o debug=splitargs afectando sólo a la traducción en español.
Así, este alias de módulo se puede usar como un módulo normal:
[type:test] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
opt_it:"-L UTF-8" opt_fr:-v
Tenga en cuenta que puede especificar opciones adicionales para cada fichero.
Modo dividido
El modo dividido («split mode») se usa cuando $master aparece en la línea de [po4a_paths].
Cuando se usa el modo dividido, se usarán unos grandes ficheros POT y PO temporales. Esto permite
compartir las traducciones entre todos los PO.
Si dos PO tienen diferentes traducciones de la misma cadena, po4a marcará esta cadena como difusa
(«fuzzy») y mandará ambas traducciones a todos los PO que contengan está cadena. Entonces, cuando un
traductor actualice la traducción y elimine la etiqueta de cadena difusa en un sólo PO, se actualizará
automáticamente la traducción de esta cadena en cada PO.
Si hay un conflicto porque varios ficheros tienen el mismo nombre de fichero, puede especificar el nombre
del fichero maestro añadiendo la opción "master:file="nombre.
[po4a_langs] de fr ja
[po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
[type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
[type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui
OPCIONES
-k, --keep
El umbral mínimo del porcentaje de traducción para preservar (es decir, escribir) el fichero
resultante (predefinido: 80). Es decir, por omisión los ficheros deben estar traducidos como mínimo
en un 80% para que se escriba el fichero resultante.
-h, --help
Muestra un mensaje corto de ayuda.
-M, --master-charset
El juego de caracteres de los ficheros que contienen los documentos a traducir. Tenga en cuenta que
por ahora todos los documentos originales deben usar el mismo juego de caracteres. Esta es una
limitación conocida, y estamos trabajando para solucionarla.
-L, --localized-charset
El juego de caracteres de los ficheros que contienen los documentos traducidos. Tenga en cuenta que
por ahora todos los documentos traducidos deben usar el mismo juego de caracteres. Esta es una
limitación conocida, y estamos trabajando para solucionarla.
-A, --addendum-charset
El juego de caracteres del apéndice. Todos los apéndices deben usar el mismo juego de caracteres.
-V, --version
Muestra la versión del script y cierra
-v, --verbose
Aumenta la cantidad de mensajes informativos del programa.
-q, --quiet
Disminuye la cantidad de mensajes informativos del programa.
-d, --debug
Devuelve por la salida información de depuración de fallos.
-o, --option
Opción(es) adicionales a introducir a la extensión del formato. Especifique cada opción con el
formato «nombre=valor». Consulte la documentación de cada extensión para más información acerca de
las opciones aceptadas y su significado.
-f, --force
Siempre genera los ficheros POT y PO, incluso si po4a no lo considera necesario.
El comportamiento predefinido (cuando no se especifica --force) es el siguiente:
Si ya existe el fichero POT, se generará otra vez si el documento original o el fichero de
configuración es más reciente. El fichero POT se escribe también en un documento temporal y po4a
comprueba si los cambios son realmente necesarios.
Así mismo, una traducción se genera otra vez sólo si el documento original, el fichero PO, uno de
sus apéndices o el fichero de configuración son más recientes. Para evitar generar otra vez las
traducciones que no pasan el análisis del umbral (consulte --keep), puede crear un fichero con
la extensión .po4a-stamp (consulte <B--stamp>).
Debería usar la marca --force si el documento original incluye ficheros, ya que no se toma en cuenta
la fecha de modificación de estos ficheros incluidos.
Los ficheros PO siempre se regeneran en base al POT con msgmerge -U.
--stamp
Activa la creación de ficheros de marcas («stamp files») cuando no se ha generado una traducción al
no alcanzar éste el umbral. Estos ficheros de marcas se nombran de acuerdo al documento traducido
esperado, con la extensión .po4a-stamp.
Nota: Esto sólo activa la creación de ficheros .po4a-stamp. En caso de existir siempre se usarán
estos ficheros, y se eliminan con --rm-translations o cuando el fichero está completamente traducido.
--no-translations
No genera los documentos traducidos, sólo actualiza los ficheros POT y PO.
--no-update
Impide modificar los ficheros POT y PO, solo se actualiza la traducción.
--keep-translations
Preserva los ficheros traducidos existentes incluso si la traducción no satisface el umbral
especificado por --keep. Esta opción no crea ficheros traducidos nuevos con escaso contenido, pero
guarda las traducciones existentes incompletas debido a cambios en los ficheros originales.
ADVERTENCIA: Esta opción modifica el comportamiento de po4a de forma muy notable: los ficheros
traducidos no se actualizan en absoluto hasta mejorar la traducción. Utilice esta opción solo en caso
de preferir la distribución de documentación traducida anticuada en lugar de distribuir una
documentación no traducida precisa.
--rm-translations
Elimina los ficheros traducidos (implica --no-translations).
--no-backups
A partir de la versión 0.41, esta opción no tiene ningún efecto. Puede que se elimine en alguna
futura publicación.
--rm-backups
A partir de la versión 0.41, esta opción no tiene ningún efecto. Puede que se elimine en alguna
futura publicación.
--translate-only fichero-traducido
Traduce sólo el fichero especificado. Puede ser útil para agilizar el proceso si el fichero de
configuración contiene muchos ficheros. Tenga en cuenta que esta opción no actualiza los ficheros PO
y POT. Puede usar esta opción varias veces.
--variable var=valor
Define una variable que se expandirá en el fichero de configuración de po4a. Cada aparición de $(var)
se reemplazará por valor. Puede introducir está opción varias veces.
--srcdir SRCDIR
Define el directorio base de todos los documentos de entrada especificados en el fichero de
configuración de po4a.
--destdir DESTDIR
Define el directorio base de todos los documentos de salida especificados en el fichero de
configuración de po4a.
OPCIONES DE MODIFICACIÓN DE CABECERA DE POT
--porefs type[,wrap|nowrap]
Define el forma de referencia: El argumento type puede ser never para no generar ninguna referencia,
file para solo especificar el fichero el número de línea, counter para sustituir el número de línea
con un recuento ascendente, y full para incluir referencias completas (predefinido: full).
El argumento puede preceder a una coma y a la palabra clave wrap o nowrap. Las referencias se
escriben en una sola línea por omisión. La opción wrap justifica las referencias en varias líneas,
para imitar a las herramientas gettext (xgettext y msgmerge). Esta opción será el comportamiento
predefinido en el futuro, ya que es más inteligente. La opción nowrap está disponible para aquellos
usuarios que deseen mantener el comportamiento antiguo.
--msgid-bugs-address email@address
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 string
Define el propietario del copyright 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».
OPCIONES DE MODIFICACIÓN DE FICHEROS PO
--msgmerge-opt opciones
Opciones adicionales para msgmerge(1).
Nota: $lang se expandirá al idioma actual.
--no-previous
Esta opción añade --previous a las opciones introducidas a msgmerge. Esto permite la compatibilidad
con versiones de gettext anteriores a 0.16.
--previous
Esta opción añade --previous a las opciones introducidas a msgmerge. Requiere gettext 0.16 o
posterior, y está activada por omisión.
EJEMPLO
Supongamos que es el responsable de un programa llamado foo, que tiene una página de manual man/foo.1 que
naturalmente sólo se mantiene en inglés. Ahora, al ser el mantenedor o encargado, desea crear y gestionar
la traducción. Primero, cree el fichero POT, necesario para su envío a los traductores, usando
po4a-gettextize(1).
En nuestro caso, invocaríamos:
cd man && po4a-gettextize -f man -m foo.1 -p foo.pot
Ahora puede enviar este fichero a las listas de idioma adecuados u ofrecerlo para su descarga en su
página web.
Supongamos ahora que ha recibido tres traducciones antes de su siguiente publicación: de.po (incluyendo
el apéndice, «addendum», de.add), sv.po y pt.po. Ya que no desea modificar el o los ficheros Makefile
cada vez que recibe una traducción nueva, puede usar po4a dentro de su Makefile creando un fichero de
configuración adecuado. Le llamaremos po4a.cfg. En nuestro ejemplo, presentaría el siguiente aspecto:
[po_directory] man/po4a/po/
[type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"
En este ejemplo suponemos que sus páginas de manual generadas (y todos los ficheros PO y de apéndice) se
guardan en man/translated/$lang, (respectivamente en man/po4a/po/ y man/po4a/add_$lang/) bajo el
directorio actual. En nuestro ejemplo, este directorio incluiría de.po, de.add, pt.po y sv.po, y el
directorio man/po4a/add_de/ incluiría de.add.
Note el uso del modificador ?, ya que sólo la traducción al alemán (de.po) viene acompañado de un
apéndice.
Para generar realmente las páginas de manual tendría que añadir (¡una sola vez!) la siguiente línea en el
«target» de construcción del fichero Makefile adecuado:
po4a po4a.cfg
Una vez que configure esto, no tendrá que tocar el Makefile cada vez que reciba una traducción nueva. Por
ejemplo, si el equipo francés envía fr.po y fr.add simplemente tendría que guardarlo en man/, y la
siguiente vez que construya el programa la traducción al francés se generará automáticamente.
Tenga en cuenta que es aún necesario un destino adecuado dónde instalar las páginas de manual traducidas
con las páginas en inglés.
Por último, si no guarda los ficheros generados en su sistema de control de versiones, necesitara también
una línea en su target clean:
-rm -rf man/translated
DEFICIENCIAS
• Dúplica el código de algunos de los programas po4a-*.
Los parches son bienvenidos ;)
VÉASE TAMBIÉN
po4a-gettextize(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-2012 by SPI, inc.
Esto es software libre; puede redistribuirlo y/o modificarlo bajo las condiciones de la licencia GPL
(consulte el fichero COPYING).
Herramientas de po4a 2020-04-15 PO4A(1p)