Provided by: po4a_0.52-1_all bug

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 áreas donde no eran de esperar, 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.

       La corriente 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.

        master document --> ficheros PO --> traducciones

       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

       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>)*\
                          (add_<idioma>:<argumento>*<ruta_al_apéndice>)*

       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 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] data-05/test2_man.1 $lang:tmp/test2_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.

       Este alias de módulo se puede usar como un módulo normal:

        [type:test] data-05/test2_man.1 $lang:tmp/test2_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 crear (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 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
           Do not change the POT and PO files, only the translation may be updated.

       --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]
           Specify the reference format. Argument type can be one of never to not produce any
           reference, file to only specify the file without the line number, counter to replace
           line number by an increasing counter, and full to include complete references
           (default: 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
           Extra options for 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-build(1), po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1),
       po4a-build.conf(5), 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).