Provided by: po4a_0.41-1ubuntu1_all bug

NOMBRE

       po4a - Actualiza los ficheros PO y los documentos traducidos a la vez

SINOPSIS

       po4a [opciones] fichero_de_configuraci'on

DESCRIPCI'ON

       El objetivo del proyecto po4a (<<PO for anything>>, PO para todo) es
       facilitar la traduccion (y mas interesante, el mantenimiento de las
       traducciones) usando las herramientas de gettext en areas donde no eran
       de esperar, como la documentacion.

       El programa po4a es util cuando no desea invocar po4a-gettextize(1),
       po4a-updatepo(1), y po4a-translate(1) a traves 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 esta organizado de la siguiente forma:

   DESCRIPCI'ON
   INTRODUCCI'ON
   SINTAXIS DEL FICHERO DE CONFIGURACI'ON
       Especificar las plantillas de idiomas

       Especificar las rutas a las entradas del traductor

       Detecci'on autom'atica de las rutas e idiomas

       Especificar los documentos a traducir

       Especificar las opciones para los m'odulos

       Especificar un alias

       Modo dividido

   OPCIONES
   EJEMPLO
   DEFICIENCIAS
   V'EASE TAMBI'EN
   AUTORES
   DERECHO DE COPIA Y LICENCIA

INTRODUCCI'ON

       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 linea
       de ordenes.

       Tambien le permite mezclar documentos en diferentes formatos en un
       mismo fichero POT, de manera que pueda tener un solo fichero por
       proyecto.

       Este comportamiento se puede imitar con las otras herramientas del
       paquete po4a (por ejemplo con ficheros <<Makefile>>), pero es bastante
       dificil 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 quedara reflejado en los ficheros PO, y
       todo cambio en los ficheros PO (manual o causado por el paso anterior)
       quedara 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 sobreescribira 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'ON

       El argumento (obligatorio) es la ruta al fichero de configuracion a
       usar. Su sintaxis intenta ser simple y parecida a la de los ficheros de
       configuracion usados por los proyectos intl-tools.

       Los comentarios en estos ficheros se indican con el caracter <<#>>.
       Comenta todo hasta el final de linea. Las lineas se pueden continuar
       escapando el final de linea. Todas las lineas con contenido deben
       empezar con una orden [], seguida por sus argumentos. (Suena dificil
       dicho asi, pero es mas bien facil, espero ;).

   Especificar las plantillas de idiomas
       Nota: Recomendamos usar [po_directory] en lugar de [po4a_langs] y
       [po4a_paths]. Consulte la seccion Detecci'on autom'atica de las rutas e
       idiomas.

       Esta es una orden opcional que puede simplificar todo el fichero de
       configuracion, y lo hara mas escalable. Debe especificar una lista de
       los idiomas a los que desee traducir los documentos. Es asi de simple:

        [po4a_langs] fr de

       Esto le permitira expandir $lang a todos los idiomas especificados en
       el resto del fichero de configuracion.

   Especificar las rutas a las entradas del traductor
       Nota: Recomendamos usar [po_directory] en lugar de [po4a_langs] y
       [po4a_paths]. Consulte la seccion Detecci'on autom'atica de las rutas e
       idiomas.

       Primero debe especificar la ubicacion 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 linea:

        [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

       Tambien puede usar $master para referirse al nombre base del documento.
       En este caso po4a usara un modo dividido: se creara un POT y un PO (por
       cada idioma) por cada documento especificado en el fichero de
       configuracion de po4a. Consulte la seccion Modo dividido (<<Split
       Mode>>).

        [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

   Detecci'on autom'atica 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 detectara el fichero
       POT como el unico fichero *.pot en el directorio especificado. po4a
       usara tambien la lista de ficheros *.po para definir la lista de
       idiomas (eliminando la extension). Estos idiomas se usaran como
       sustitucion de la variable $lang en el resto del fichero de
       configuracion.

       No deberia usar esta orden en combinacion con las ordenes [po4a_langs]
       o [po4a_paths].

       Al usar esta orden, tiene que crear un fichero POT vacio al ejecutar
       po4a por primera vez para asi dar a conocer el nombre del fichero POT.

        [po_directory] po4a/po/

   Especificar los documentos a traducir
       Naturalmente, debe especificar que documentos estan traducidos, su
       formato, y donde guardar sus traducciones. Se puede hacer con lineas
       como las siguientes:

        [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
                     de:doc/de/mein_cram.sgml
        [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
                    add_fr:doc/l10n/script.fr.add

       Esto tambien se deberia explicar por si mismo. Tenga en cuenta que en
       el segundo caso, doc/l10n/script.fr.add es un apendice a (<<addenda>>)
       anadir a la version francesa del documento. Consulte po4a(7) para mas
       informacion sobre los apendices.

       Mas formalmente, el formato es:

        [type: <formato>] <doc_original> (<idioma>:<doc_traducido>)*\
                          (add_<idioma>:<argumento>*<ruta_al_apendice>)*

       De no existir argumentos, ruta_al_ap'endice es la ruta a un apendice.
       Los argumentos son

       ? Incluye ruta_al_ap'endice si el fichero si existe, y no hace nada de
         lo contrario.

       @ ruta_al_ap'endice no es un apendice normal, sino un fichero que
         contiene una lista de apendices, uno por linea. Cada apendice puede
         ir precedido de argumentos.

       ! Si ruta_al_ap'endice se descarta, no se cargara, independientemente de
         cualquier especificacion adicional referida al apendice.

       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 apendices con rutas similares, tambien
       podria escribir algo asi.

        [type: pod] script $lang:doc/$lang/script.1 \
                    add_$lang:doc/l10n/script.$lang.add

   Especificar las opciones para los m'odulos
       po4a acepta opciones que se introduciran al modulo. Estas opciones son
       especificas a cada modulo y se definen con la opcion -o.

       Si precisa de una opcion en particular para uno de los documentos que
       desea traducir, tambien puede especificarla en el fichero de
       configuracion. Las opciones se introducen con la palabra clave opt.
       Debe entrecomillar el argumento de la palabra clave opt si este
       contiene un espacio (por ejemplo, si especifica varias opciones, o una
       opcion con un argumento). Puede tambien especificar opciones que solo
       afectaran 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 continuacion la seccion
       Especificar un alias).

       Tambien puede configurar opciones para todos los documentos
       especificados en el fichero de configuracion:
        [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 modulo. Puede hacer esto de
       la siguiente forma:

       [po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"

       Esto define un alias de modulo llamado test, basado en el modulo man, y
       en el que -k 21 afecta a todos los idiomas, con -o debug=splitargs
       afectando solo a la traduccion en espanol.

       Este alias de modulo se puede usar como un modulo 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
       linea de [po4a_paths].

       Cuando se usa el modo dividido, se usaran 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
       marcara esta cadena como difusa (<<fuzzy>>) y mandara ambas
       traducciones a todos los PO que contengan esta cadena. Entonces, cuando
       un traductor actualice la traduccion y elimine la etiqueta de cadena
       difusa en un solo PO, se actualizara automaticamente la traduccion de
       esta cadena en cada PO.

OPCIONES

       -k, --keep
           El umbral minimo del porcentaje de traduccion para crear (es decir,
           escribir) el fichero resultante (predefinido: 80). Es decir, por
           omision los ficheros deben estar traducidos como minimo 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
           limitacion 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
           limitacion conocida, y estamos trabajando para solucionarla.

       -A, --addendum-charset
           El juego de caracteres del apendice. Todos los apendices deben usar
           el mismo juego de caracteres.

       -V, --version
           Muestra la version 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 informacion de depuracion de fallos.

       -o, --option
           Opcion(es) adicionales a introducir a la extension del formato.
           Especifique cada opcion con el formato <<nombre=valor>>. Consulte
           la documentacion de cada extension para mas informacion 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 generara otra vez si el
               documento original o el fichero de configuracion es mas
               reciente. El fichero POT se escribe tambien en un documento
               temporal y po4a comprueba si los cambios son realmente
               necesarios.

               Asi mismo, una traduccion se genera otra vez solo si el
               documento original, el fichero PO, uno de sus apendices o el
               fichero de configuracion son mas recientes. Para evitar generar
               otra vez las traducciones que no pasan el analisis  del umbral
               (consulte --keep), puede crear un fichero con la extension
               .po4a-stamp (consulte <B--stamp>).

           Deberia usar la marca --force si el documento original incluye
           ficheros, ya que no se toma en cuenta la fecha de modificacion de
           estos ficheros incluidos.

           Los ficheros PO siempre se regeneran en base al POT con msgmerge
           -U.

       --stamp
           Activa la creacion de ficheros de marcas (<<stamp files>>) cuando
           no se ha generado una traduccion al no alcanzar este el umbral.
           Estos ficheros de marcas se nombran de acuerdo al documento
           traducido esperado, con la extension .po4a-stamp.

           Nota: Esto solo activa la creacion de ficheros .po4a-stamp. En caso
           de existir siempre se usaran estos ficheros, y se eliminan con
           --rm-translations o cuando el fichero esta completamente traducido.

       --no-translations
           No genera los documentos traducidos, solo actualiza los ficheros
           POT y PO.

       --rm-translations
           Elimina los ficheros traducidos (implica --no-translations).

       --no-backups
           A partir de la version 0.41, esta opcion no tiene ningun efecto.
           Puede que se elimine en alguna futura publicacion.

       --rm-backups
           A partir de la version 0.41, esta opcion no tiene ningun efecto.
           Puede que se elimine en alguna futura publicacion.

       --translate-only fichero-traducido
           Traduce solo el fichero especificado. Puede ser util para agilizar
           el proceso si el fichero de configuracion contiene muchos ficheros.
           Tenga en cuenta que esta opcion no actualiza los ficheros PO y POT.
           Puede usar esta opcion varias veces.

       --variable var=valor
           Define una variable que se expandira en el fichero de configuracion
           de po4a. Cada aparicion de $(var) se reemplazara por valor. Puede
           introducir esta opcion varias veces.

       --msgid-bugs-address email@address
           Define el destinatario de los informes de fallo en los msgid. Por
           omision, 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
           omision es <<PACKAGE>>.

       --package-version string
           Define la version del paquete en la cabecera del POT. El valor por
           omision es <<VERSION>>.

       --msgmerge-opt opciones
           Opciones adicionales para msgmerge.

           Nota: $lang se expandira al idioma actual.

       --no-previous
           Esta opcion anade --previous a las opciones introducidas a
           msgmerge. Esto permite la compatibilidad con versiones de gettext
           anteriores a 0.16.

       --previous
           Esta opcion anade --previous a las opciones introducidas a
           msgmerge. Requiere gettext 0.16 o posterior, y esta activada por
           omision.

       --srcdir SRCDIR
           Define el directorio base de todos los documentos de entrada
           especificados en el fichero de configuracion de po4a.

       --destdir DESTDIR
           Define el directorio base de todos los documentos de salida
           especificados en el fichero de configuracion de po4a.

   EJEMPLO
       Supongamos que es el responsable de un programa llamado foo, que tiene
       una pagina de manual man/foo.1 que naturalmente solo se mantiene en
       ingles. Ahora, al ser el mantenedor o encargado, desea crear y
       gestionar la traduccion. Primero, cree el fichero POT, necesario para
       su envio a los traductores, usando po4a-gettextize(1).

       En nuestro caso, invocariamos:

        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 pagina web.

       Supongamos ahora que ha recibido tres traducciones antes de su
       siguiente publicacion: de.po (incluyendo el apendice, <<addendum>>,
       de.add), sv.po y pt.po. Ya que no desea modificar el o los ficheros
       Makefile cada vez que recibe una traduccion nueva, puede usar po4a
       dentro de su Makefile creando un fichero de configuracion adecuado. Le
       llamaremos po4a.cfg. En nuestro ejemplo, presentaria 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 paginas de manual generadas (y todos
       los ficheros PO y de apendice) 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 incluiria de.po,
       de.add, pt.po y sv.po, y el directorio man/po4a/add_de/ incluiria
       de.add.

       Note el uso del modificador ?, ya que solo la traduccion al aleman
       (de.po) viene acompanado de un apendice.

       Para generar realmente las paginas de manual tendria que anadir (iuna
       sola vez!) la siguiente linea en el <<target>> de construccion del
       fichero Makefile adecuado:

               po4a po4a.cfg

       Una vez que configure esto, no tendra que tocar el Makefile cada vez
       que reciba una traduccion nueva. Por ejemplo, si el equipo frances
       envia fr.po y fr.add simplemente tendria que guardarlo en man/, y la
       siguiente vez que construya el programa la traduccion al frances se
       generara automaticamente.

       Tenga en cuenta que es aun necesario un destino adecuado donde instalar
       las paginas de manual traducidas con las paginas en ingles.

       Por ultimo, si no guarda los ficheros generados en su sistema de
       control de versiones, necesitara tambien una linea en su target clean:
               -rm -rf man/translated

DEFICIENCIAS

       o   Duplica el codigo de algunos de los programas po4a-*.

       Los parches son bienvenidos ;)

V'EASE TAMBI'EN

       po4a(7), po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1),
       po4a-normalize(1), po4a-build(1), po4a-build.conf(5).

AUTORES

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

DERECHO DE COPIA Y LICENCIA

       Copyright 2002-2010 by SPI, inc.

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