Available in

(1) (7) (1)/ca (7)/ca (1)/es (7)/es (1)/fr (7)/fr (1)/it (1)/ja (7)/ja (1)/pl (7)/pl

Contents

NOMBRE

po4a − Actualizar 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 all», 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 en 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 ciertos documentos.

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

Auto−detección de las rutas e idiomas

Especificar los documentos a traducir

Especificar las opciones de los módulos

Especificar 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 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 difícil 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, véase po4a−gettextize(1).

SINTAXIS DEL FICHERO DE CONFIGURACIÓN

El argumento (obligatorio) es la ruta del 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 «#». Esto lo 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 Auto−detección de las rutas e idiomas.

Esta 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 Auto−detección de las rutas e idiomas.

Primero debe especificar dónde están los ficheros de entrada del traductor (es decir, los ficheros que utilizan los traductores para hacer su trabajo). Esto se puede hacer con una línea 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

También 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 configuración de po4a. Véase la sección Modo dividido («Split Mode»).

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

Auto−detección 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í hacerle saber 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_cram.sgml
 [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
             add_fr:doc/l10n/script.fr.add

Esto también debería explicarse por si mismo. Tenga en cuenta que en el segundo caso, «doc/l10n/script.fr.add» es un apéndice a 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_principal> <idioma>:<doc_traducido>*
                   add_<idioma>:<argumentos>*<ruta_al_apéndice>*

De no existir argumentos, ruta_al_apéndice es la ruta a un apéndice. Los modificadores son

?

Incluir ruta_al_apéndice si el fichero existe, y no hacer 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 así:

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

Si todos los idiomas tienen apéndices con rutas similares, puede también escribir algo así.

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

Especificar las opciones de los módulos
po4a acepta opciones, que se pasan al módulo. Estas opciones son específicas a cada módulo y definidas 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 (p. ej., si especifica varias opciones, y o una opción con un argumento). Puede también 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 (véase a continuación la sección Especificar alias).

También puede definir opciones para todos los documentos especificados en el fichero de configuración:
[options] opt:"..." opt_fr:"..."

Especificar 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>, −k 21 afectando a todos los idiomas y con −o debug=splitargs, que sólo afectará a la versió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

Observe que puede especificar opciones adicionales de manera individual.

Modo dividido
El modo dividido se usa cuando «$master» aparece en la línea de [po4a_paths].

Mientras esté en uso el modo dividido, se usarán 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 traducción, y elimina la etiqueta de cadena borrosa («fuzzy») en un PO , se actualizará automáticamente la traducción de esta cadena en cada PO .

OPCIONES

−k, −−keep

El umbral mínimo del porcentaje de traducción para mantener (es decir, escribir) el fichero resultante (defecto: 80). Es decir, por omisión los ficheros deben estar traducidos como mínimo 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 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

Mostrar la versión 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 información de depuración fallos.

−o, −−option

Opción(es) adicionales que pasar a la extensión del formato. Especifique cada opción en el formato ’nombre=valor’. Véase la documentación de cada extensión para más información acerca de las opciones válidas 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 configuración es más reciente. El fichero POT se escribe también en un documento temporal y po4a revisa si los cambios son realmente necesarios.

Así mismo, una traducción se genera otra vez sólo si el documento original, el fichero PO , una de sus apéndices o el fichero de configuración son más recientes. Para evitar generar nuevamente las traducciones que no pasan el umbral del examen (véase −−keep), puede crear un fichero con la extensión ’.po4a−stamp’ (véase <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 se generan otra vez en base al POT con msgmerge −U.

−−stamp

Activar la creación de ficheros de marcas 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 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 sólo el fichero especificado. Puede ser útil para agilizar el procesado 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

Definir 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.

−−msgid−bugs−address email@address

Definir el destinatario de los informas de fallo de los msgid. Por omisión, 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 omisión es «PACKAGE».

−−package−version string

Definir la versión del paquete en la cabecera del POT . El valor por omisión es «VERSION».

−−msgmerge−opt opciones

Opciones adicionales para msgmerge.

Nota: $lang se expandirá al idioma presente.

−−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.

−−srcdir SRCDIR

Definir el directorio base de todos los documentos de entrada especificados en el fichero de configuración de po4a.

−−destdir DESTDIR

Definir el directorio base de todos los documentos de salida especificados en el fichero de configuración de po4a.

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 apropiados 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/
 [type: man] foo.1 $lang:man/foo.$lang.1 \
            add_$lang:?man/foo.$lang.add opt:"−k 80"

En este ejemplo, suponemos que sus páginas de manual generados (y todos los ficheros po y de apéndice) se guardan en man/, bajo el directorio actual. En nuestro ejemplo, este directorio incluiría de.po, de.add, pt.po y sv.po.

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, 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 «clean target»:
−rm −f man/foo.*.1
−rm −f man/foo.pot

DEFICIENCIAS

Dúplica el código de algunos de los programas po4a−*.

Los parches son bienvenidos ;)

VÉASE TAMBIÉN

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

AUTORES

 Denis Barbier <barbier [AT] linuxfr.org>
 Nicolas François <nicolas.francois [AT] 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 (véase el fichero COPYING ).

COMMENTS

blog comments powered by Disqus