Provided by: po4a_0.40-1_all bug

NOMBRE

       po4a - Actualizar los ficheros po y los documentos traducidos a la vez

SINOPSIS

       po4a [opciones] <fichero_de_configuracin>

DESCRIPCIN

       El objetivo del proyecto po4a (po for all, po para todo) es facilitar
       la traduccin (y ms interesante, el mantenimiento de las traducciones)
       usando las herramientas de gettext en reas donde no eran de esperar,
       como en la documentacin.

       El programa po4a es til cuando no desea invocar po4a-gettextize(1),
       po4a-updatepo(1), y po4a-translate(1) a travs de complejos ficheros
       Makefile cuando tiene varios ficheros a traducir, diferentes formatos o
       necesita especificar diferentes opciones para ciertos documentos.

Tabla de contenidos

       Este documento est organizado de la siguiente forma:

   DESCRIPCIN
   INTRODUCCIN
   SINTAXIS DEL FICHERO DE CONFIGURACIN
       Especificar las plantillas de idiomas

       Especificar las rutas a las entradas del traductor

       Auto-deteccin de las rutas e idiomas

       Especificar los documentos a traducir

       Especificar las opciones de los mdulos

       Especificar alias

       Modo dividido

   OPCIONES
   EJEMPLO
   DEFICIENCIAS
   VASE TAMBIN
   AUTORES
   DERECHO DE COPIA Y LICENCIA

INTRODUCCIN

       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 lnea
       de rdenes.

       Tambin le permite mezclar documentos en diferentes formatos en el mismo
       fichero pot, de manera que puede 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
       difcil y agotador el tener que rehacer los mismos ficheros para cada
       proyecto que utilice 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 (bien manual o causado por el paso
       anterior) quedar reflejado en los documentos traducidos.

        master document --> po files --> translations

       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, vase
       po4a-gettextize(1).

SINTAXIS DEL FICHERO DE CONFIGURACIN

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

       Los comentarios en estos ficheros se indican con el carcter #. Esto lo
       comenta todo hasta el final de lnea. Las lneas se pueden continuar
       escapando el final de lnea. Todas las lneas con contenido deben empezar
       con una orden [], seguida por sus argumentos. (Suena difcil dicho as,
       pero es ms bien fcil, espero ;).

   Especificar las plantillas de idiomas
       Nota: Recomendamos usar [po_directory] en lugar de [po4a_langs] y
       [po4a_paths]. Consulte la seccin Auto-deteccin de las rutas e idiomas.

       Esta es una orden opcional que puede simplificar todo el fichero de
       configuracin, y lo har ms 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 configuracin.

   Especificar las rutas a las entradas del traductor
       Nota: Recomendamos usar [po_directory] en lugar de [po4a_langs] y
       [po4a_paths]. Consulte la seccin Auto-deteccin de las rutas e idiomas.

       Primero debe especificar dnde estn los ficheros de entrada del
       traductor (es decir, los ficheros que utilizan los traductores para
       hacer su trabajo). Esto se puede hacer con una lnea as:

        [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 as:

        [po4a_paths] doc/l10n/proyecto.doc.pot $lang:doc/l10n/$lang.po

       Tambin puede usar $master para referirse al nombre base del documento.
       En este caso po4a usar un modo dividido: se crear un pot y un po (por
       cada idioma) con cada documento especificado en el fichero de
       configuracin de po4a. Vase la seccin Modo dividido (Split Mode).

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

   Auto-deteccin 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
       tambin la lista de ficheros *.po para definir la lista de idiomas
       (eliminando la extensin). Estos idiomas se usarn como sustitucin de la
       variable $lang en el resto del fichero de configuracin.

       No debera usar esta orden en combinacin con las rdenes po4a_langs o
       po4a_paths.

       Al usar esta orden, tiene que crear un fichero pot vaco al ejecutar
       po4a por primera vez, para as hacerle saber el nombre del fichero pot.

        [po_directory] po4a/po/

   Especificar los documentos a traducir
       Naturalmente, debe especificar qu documentos estn traducidos, su
       formato, y dnde guardar sus traducciones. Se puede hacer con lneas 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 tambin debera explicarse por si mismo. Tenga en cuenta que en el
       segundo caso, doc/l10n/script.fr.add es un apndice a aadir a la versin
       francesa del documento. Consulte po4a(7) para ms informacin sobre los
       apndices.

       Ms formalmente, el formato es:

        [type: <formato>] <doc_principal> <idioma>:<doc_traducido>*
                          add_<idioma>:<argumentos>*<ruta_al_apndice>*

       De no existir argumentos, ruta_al_apndice es la ruta a un apndice. Los
       modificadores son

       ? Incluir ruta_al_apndice si el fichero existe, y no hacer nada de lo
         contrario.

       @ ruta_al_apndice no es un apndice normal, sino un fichero que contiene
         una lista de apndices, uno por lnea. Cada apndice puede ir precedido
         de argumentos.

       ! Si ruta_al_apndice se descarta, no se cargar, independientemente de
         cualquier especificacin adicional referida al apndice.

       Si ha definido la plantilla de idiomas, puede reescribir la linea
       anterior as:

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

       Si todos los idiomas tienen apndices con rutas similares, puede tambin
       escribir algo as.

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

   Especificar las opciones de los mdulos
       po4a acepta opciones, que se pasan al mdulo. Estas opciones son
       especficas a cada mdulo y definidas con la opcin -o.

       Si precisa de una opcin en particular para uno de los documentos que
       desea traducir, tambin puede especificarla en el fichero de
       configuracin. Las opciones se introducen con la palabra clave opt. Debe
       entrecomillar el argumento de la palabra clave opt si ste contiene un
       espacio (p. ej., si especifica varias opciones, y o una opcin con un
       argumento). Puede tambin especificar opciones qu solo afectan 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
       normales 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 (vase a continuacin la seccin Especificar
       alias).

       Tambin puede definir opciones para todos los documentos especificados
       en el fichero de configuracin:
        [options] opt:"..." opt_fr:"..."

   Especificar alias
       Si tiene que especificar las mismas opciones para varios ficheros,
       puede que le interese definir un alias de mdulo. Puede hacer esto de la
       siguiente forma:

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

       Esto define un alias de mdulo llamado test, basado en el mdulo <man>,
       -k 21 afectando a todos los idiomas y con -o debug=splitargs, que slo
       afectar a la versin en espaol.

       Este alias de mdulo se puede usar como un mdulo normal:

       [type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
                   opt_it:"-L UTF-8" opt_fr:-v

       Observe que puede especificar opciones adicionales de manera
       individual.

   Modo dividido
       El modo dividido se usa cuando $master aparece en la lnea de
       [po4a_paths].

       Mientras est en uso el modo dividido, se usarn unos grandes 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 borrosa y mandar ambas traducciones a todos los
       PO que contengan est cadena. Entonces, cuando un traductor actualice la
       traduccin, y elimina la etiqueta de cadena borrosa (fuzzy) en un PO, se
       actualizar automticamente la traduccin de esta cadena en cada PO.

OPCIONES

       -k, --keep
           El umbral mnimo del porcentaje de traduccin para mantener (es
           decir, escribir) el fichero resultante (defecto: 80). Es decir, por
           omisin los ficheros deben estar traducidos como mnimo en un 80%
           para que se escriba el resultado.

       -h, --help
           Mostrar 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
           limitacin 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
           limitacin conocida, y estamos trabajando para solucionarla.

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

       -V, --version
           Mostrar la versin del script y cerrar.

       -v, --verbose
           Aumentar la cantidad de mensajes informativos del programa.

       -q, --quiet
           Disminuir la cantidad de mensajes informativos del programa.

       -d, --debug
           Devolver informacin de depuracin fallos.

       -o, --option
           Opcin(es) adicionales que pasar a la extensin del formato.
           Especifique cada opcin en el formato 'nombre=valor'. Vase la
           documentacin de cada extensin para ms informacin acerca de las
           opciones vlidas y sus significados.

       -f, --force
           Generar siempre los ficheros POT y POT, incluso si po4a no lo
           considera necesario.

           El comportamiento predeterminado (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 configuracin es ms reciente.
               El fichero POT se escribe tambin en un documento temporal y
               po4a revisa si los cambios son realmente necesarios.

               As mismo, una traduccin se genera otra vez slo si el documento
               original, el fichero PO, una de sus apndices o el fichero de
               configuracin son ms recientes. Para evitar generar nuevamente
               las traducciones que no pasan el umbral del examen (vase
               --keep), puede crear un fichero con la extensin '.po4a-stamp'
               (vase <B--stamp>).

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

           Los ficheros PO se generan otra vez en base al POT con msgmerge -U.

       --stamp
           Activar la creacin de ficheros de marcas cuando no se ha generado
           una traduccin al no alcanzar ste el umbral. Estos ficheros de
           marcas se nombran de acuerdo al documento traducido esperado, con
           la extensin .po4a-stamp.

           Nota: Esto slo activa la creacin de ficheros .po4a-stamp. En caso
           de existir siempre se usarn estos ficheros, y se eliminan con
           --rm-translations o cuando el fichero est completamente traducido.

       --no-translations
           No generar los documentos traducidos, pero solo actualizar los
           ficheros POT y PO.

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

       --no-backups
           No generar los las copias de seguridad .po~.

       --rm-backups
           Eliminar las copias de seguridad .po~ (implica --no-backups).

       --translate-only fichero-traducido
           Traduce slo el fichero especificado. Puede ser til para agilizar el
           procesado si el fichero de configuracin contiene muchos ficheros.
           Tenga en cuenta que esta opcin no actualiza los ficheros PO y POT.
           Puede usar esta opcin varias veces.

       --variable var=valor
           Definir una variable que se expandir en el fichero de configuracin
           de po4a. Cada aparicin de $(var) se reemplazar por valor. Puede
           introducir est opcin varias veces.

       --msgid-bugs-address email@address
           Definir el destinatario de los informas de fallo de los msgid. Por
           omisin, los ficheros POT creados no tienen el campo
           Report-Msgid-Bugs-To.

       --copyright-holder string
           Definir el propietario del copyright en la cabecera del POT. El
           valor predeterminado es Free Software Foundation, Inc.

       --package-name string
           Definir el nombre del paquete en la cabecera del POT. El valor por
           omisin es PACKAGE.

       --package-version string
           Definir la versin del paquete en la cabecera del POT. El valor por
           omisin es VERSION.

       --msgmerge-opt opciones
           Opciones adicionales para msgmerge.

           Nota: $lang se expandir al idioma presente.

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

       --previous
           Esta opcin aade --previous a las opciones introducidas a msgmerge.
           Requiere gettext 0.16 o posterior, y est activada por omisin.

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

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

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

       En nuestro caso, invocaramos:

        cd man && po4a-gettextize -f man -m foo.1 -p foo.pot

       Ahora puede enviar este fichero a las listas de idioma apropiados u
       ofrecerlo para su descarga en su pgina web.

       Supongamos ahora que ha recibido tres traducciones antes de su
       siguiente publicacin: de.po (incluyendo el apndice, addendum, de.add),
       sv.po y pt.po. Ya que no desea modificar el o los ficheros makefile
       cada vez que recibe una traduccin nueva, puede usar po4a dentro de su
       makefile creando un fichero de configuracin adecuado. Le llamaremos
       po4a.cfg. En nuestro ejemplo, presentara el siguiente aspecto:

        [po_directory] man/

        [type: man] foo.1 $lang:man/foo.$lang.1 \
                   add_$lang:?man/foo.$lang.add opt:"-k 80"

       En este ejemplo, suponemos que sus pginas de manual generados (y todos
       los ficheros po y de apndice) se guardan en man/, bajo el directorio
       actual. En nuestro ejemplo, este directorio incluira de.po, de.add,
       pt.po y sv.po.

       Note el uso del modificador ?, ya que slo la traduccin al alemn (de.po)
       viene acompaado de un apndice.

       Para generar realmente las pginas de manual tendra que aadir (una sola
       vez!) la siguiente lnea en el target de construccin del fichero
       makefile adecuado:

               po4a po4a.cfg

       Una vez que configure esto, no tendr que tocar el makefile cada vez que
       reciba una traduccin nueva. Por ejemplo, el equipo francs enva fr.po y
       fr.add. Simplemente tendra que guardarlo en man/ y la siguiente vez que
       construya el programa la traduccin al francs se generar automticamente.

       Tenga en cuenta que es an necesario un destino adecuado dnde instalar
       las pginas de manual traducidas con las pginas en ingls.

       Por ltimo, si no guarda los ficheros generados en su sistema de control
       de versiones, necesitara tambin una lnea en clean target:
                -rm -f man/foo.*.1
               -rm -f man/foo.pot

DEFICIENCIAS

       o   Dplica el cdigo de algunos de los programas po4a-*.

       Los parches son bienvenidos ;)

VASE TAMBIN

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

AUTORES

        Denis Barbier <barbier@linuxfr.org>
        Nicolas Franois <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 (vase el fichero COPYING).