po4a

NOMBRE

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

SINOPSIS

po4a [opciones] fichero_de_configuración

DESCRIPCIÓN

po4a (PO para cualquier cosa) facilita el mantenimiento de la traducción de documentación utilizando las herramientas clásicas de gettext. La característica principal de po4a es que desacopla la traducción del contenido de la estructura del documento. Consulte la página po4a (7) para obtener una breve introducción a este proyecto. Upon execution, po4a parses all documentation files specified in its configuration file. It updates the PO files (containing the translation) to reflect any change to the documentation, and produce a translated documentation by injecting the content's translation (found in the PO files) into the structure of the original master document. At first, the PO files only contain the strings to translate from the original documentation. This file format allows the translators to manually provide a translation for each paragraph extracted by po4a. If the documentation is modified after translation, po4a marks the corresponding translations as "fuzzy" in the PO file to request a manual review by the translators. The translators can also provide so-called "addendum", that are extra content stating for example who did the translation and how to report bugs.

 master documents ---+---->-------->---------+
  (doc authoring)    |                       |
                     V   (po4a executions)   >-----+--> translated
                     |                       |     |     documents
 existing PO files -->--> updated PO files >-+     |
      ^                            |               |
      |                            V               |
      +----------<---------<-------+               ^
       (manual translation process)                |
                                                   |
 addendum -->--------------------------------------+

The workflow of po4a is asynchronous, as suited to open-source projects. The documentation writers author the master documents at their own pace. The translators review and update the translations in the PO files. The maintainers rerun po4a on need, to reflect any change to the original documentation to the PO files, and to produce updated documentation translations, by injecting the latest translation into the latest document structure. By default, a given translated document is produced when at least 80% of its content is translated. The untranslated text is kept in the original language. The produced documentation thus mixes languages if the translation is not complete. You can change the 80% threshold with the --keep option described below. Note however that discarding translations as soon as they are not 100% may be discouraging for the translators whose work will almost never be shown to the users, while showing "translations" that are too incomplete may be troubling for the end users. Storing the translated documentation files in the version control system is probably a bad idea, since they are automatically generated. The precious files are the PO files, that contain the hard work of your fellow translators. Also, some people find it easier to interact with the translators through an online platform such as weblate, but this is naturally fully optional.

Quick start tutorial

Let's assume you maintain a program named foo which has a man page man/foo.1 written in English (the bridge language in most open-source projects, but po4a can be used from or to any language). Some times ago, someone provided a German translation named man/foo.de.1 and disappeared. This is a problem because you just got a bug report saying that your documentation contains a gravely misleading information that must be fixed in all languages, but you don't speak German so you can only modify the original, not the translation. Now, another contributor wants to contribute a translation to Japanese, a language that you don't master either. It is time to convert your documentation to po4a to solve your documentation maintenance nightmares. You want to update the doc when needed, you want to ease the work of your fellow translators, and you want to ensure that your users never see any outdated and thus misleading documentation. The conversion includes two steps: setup the po4a infrastructure, and convert the previous German translation to salvage the previous work. This latter part is done using po4a-gettextize, as follows. As detailed in the documentation of po4a-gettextize(1), this process rarely fully automatic, but once it's done, the de.po file containing the German translation can be integrated in your po4a workflow.

  po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po

Let's now configure po4a. With the appropriate file layout, your configuration file could be as simple as this:

 [po_directory] man/po4a/
 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1

It specifies that all PO files (containing the work of the translators) are the man/po4a/ directory, and that you have only one master file, man/foo.1. If you had several master files, you would have several lines similar to the second one. Each such line also specify where to write the corresponding translation files. Here, the German translation of man/foo.1 is in man/translated/foo.de.1. The last thing we need to complete the configuration of po4a is a POT file containing the template material that should be used to start a new translation. Simply create an empty file with the .pot extension in the specified po_directory (e.g. man/po4a/foo.pot), and po4a will fill it with the expected content. Here is a recap of the files in this setup:

  ├── man/
  │   ├── foo.1        <- The original man page, in English.
  │   ├── po4a/
  │   │   ├── de.po    <- The German PO translation, from gettextization.
  │   │   └── foo.pot  <- The POT template of future translations (empty at first)
  │   └── translated/  <- Directory where the translations will be created
  └── po4a.cfg         <- The configuration file.

Once setup, executing po4a will parse your documentation, update the POT template file, use it to update the PO translation files, and use them to update the documentation translation files. All in one command:

        po4a --verbose po4a.cfg

This it. po4a is now fully configured. Once you've fixed your error in man/foo.1, the offending paragraph in the German translation will be replaced by the fixed text in English. Mixing languages is not optimal, but it's the only way to remove errors in translations that you don't even understand, and ensure that the content presented to the users is never misleading. Updating the German translation is also much easier in the corresponding PO file, so the language mix-up may not last long. Finally, when the Japanese translator gives you a jp.po translated file, just drop it in man/po4a/po/. A translated page will appear as man/translated/foo.jp.1 (provided that enough content is translated) when you run po4a again.

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 en disco.

-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 cuento que todos los documentos maestros deben usar el mismo juego de caracteres.

-L, --localized-charset

El juego de caracteres de los ficheros que contienen los documentos localizados. Tenga en cuentao que todos los documentos traducidos deben usar el mismo juego de caracteres.

-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. Consulte la documentación de cada extensión para más información acerca de las opciones aceptadas y su significado. Por ejemplo, puede pasar '-o tablecells' al intérprete AsciiDoc, mientras que el intérprete de texto aceptaría '-o tabs=split'.

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

--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. Si se especifican tanto destdir como srcdir, los archivos de entrada se buscan en los siguientes directorios, en orden: destdir, el directorio actual y srcdir. Los archivos de salida se escriben en destdir si se especifica, o en el directorio actual.

--destdir DESTDIR

Define el directorio base de todos los documentos de salida especificados en el fichero de configuración de po4a (ver --srcdir).

Opciones que modifican el encabezado POT

--porefs type

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

--wrap-po no|newlines|number (por omisión: 76)

Especifique cómo se debe ajustar el archivo po. Esto permite elegir entre archivos que están bien ajustados pero que podrían generar conflictos de git o archivos que son más fáciles de manejar automáticamente, pero más difíciles de leer para los humanos. Históricamente, la suite gettext ha reformateado los archivos po en la columna 77 por razones cosméticas. Esta opción especifica el comportamiento de po4a. Si se establece en un valor numérico, po4a ajustará el archivo po después de esta columna y después de nuevas líneas en el contenido. Si se establece en newlines, po4a solo dividirá los msgid y msgstr después de nuevas líneas en el contenido. Si se establece en no, po4a no ajustará el archivo po en absoluto. Los comentarios de referencia siempre son ajustados por las herramientas gettext que usamos internamente. Tenga en cuenta que esta opción no tiene ningún impacto en cómo se ajustan msgid y msgstr, es decir, en cómo se agregan nuevas líneas al contenido de estas cadenas.

--master-language

El idioma de los ficheros que contienen el documento a traducir. Todos los documentos maestros deben utilizar el mismo idioma.

--msgid-bugs-address correo-e@direccion

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 cadena

Define el titula de los derechos de reproducción 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 para modificar los archivos PO

--msgmerge-opt opciones

Opciones adicionales para msgmerge(1). Nota: $lang se expandirá al idioma actual.

--no-previous

Esta opción retira --previous desde las opciones aprobadas a msgmerge. Esto es necesarios para admitir 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.

ARCHIVO DE CONFIGURACIÓN

po4a espera un archivo de configuraicón como argumento. Este archivo de contener los siguientes elementos:

•

La ruta a los archivos PO y la lista de idiomas en el proyecto;

•

Opcionalmente, algunas opciones globales y los denominados alias de configuración que se utilizan como plantillas para configurar archivos maestros individuales;

•

La lista con cada archivo maestro a traducir, junto con parámetros específicos.

Todas las líneas contienen una orden entre paréntesis cuadrados, seguido de sus parámetros. Los comentarios comienzan con el carácter '#' y van hasta el final de la línea. Puede escapar el final de la línea para extender una orden en varias líneas. En esta página se presentan algunos ejemplos completos, mientras que otros ejemplos se pueden encontrar en el directorio "t/cfg" de la distribución fuente.

Encontrar los archivos PO y POT

La solución más simple es proporcionar explicitamente la ruta a los archivos POT y PO, así:

 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po

Este especifíca la ruta al archivo POT primero, y después las rutas a los archivos PO en alemán y frncés. La misma información puede escribirse como sigue para reducir el riesgo de errores de copiar/pegar:

 [po4a_langs] fr de
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

El componente $lang se expande automaticamente al usar la lista de idiomas proveida, reduciendo así el riesgo de errores de copiar/pegar cuando se añade un nuevo idioma. Puede compactar más la misma información al proporcionalr solamente la ruta al directorio que contiene su proyecto de traducción, como se describe a continuación.

 [po_directory] man/po/

El directorio proporcionado debe contener un juego de archivo PO, cada uno con un nombre de la forma XX.po siendo "XX" el código ISO 639-1 del idioma usado en ese archivo. El directorio también debe contener un sólo archivo POT, con la extensión ".pot". En la primera ejecución, este archivo debe estar vacío pero debe existir (por4a no puee adivinar el nombre por usar antes de la extensión). Note que usted debe elegir sólo uno entre "directorio_po" y "rutas_po4a". El primero ("directorio_po") es más compacto, reduciendo más el riesgo de errores de copiar7pegar, pero forzandolo a usar la estructura y nombres de archivos esperados del prooyecto. La segunda ("rutas_po4a"), es más explicita, probablemente más legible y se recomienda cuando esté montando su primer proyecto con po4a. ¿Archivos PO centralizados o divididos? De manera predeterminada, po4a produce un sólo archivo PO por idioma objetivo, que contiene el contenido completo de su proyecto de traducción. A medida que su proyecto crezca, el tamaño de estos archivos puede volverse problemático. Al usar weblate, es posible especificar prioridades para cada segmento de traducción (i.e, msgid) de forma que los importante son traducidos primero. Aún así, algunos equipos de traducción prefieren dividir el contenido en varios archivos. Para tener un archivo PO por cada archivo maestro, usted sólo tiene que usar la cadena $master en el nombre de sus archivos PO y la línea "[rutas_po4a]", como sigue.

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

With this line, po4a will produce separate POT and PO files for each document to translate. For example, if you have 3 documents and 5 languages, this will result in 3 POT files and 15 PO files. These files are named as specified on the "po4a_paths" template, with $master substituted to the basename of each document to translate. In case of name conflict, you can specify the POT file to use as follows, with the "pot=" parameter. This feature can also be used to group several translated files into the same POT file. The following example only produces 2 POT files: l10n/po/foo.pot (containing the material from foo/gui.xml) and l10n/po/bar.pot (containing the material from both bar/gui.xml and bar/cli.xml).

 [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 pot=foo
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
 [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar

En modo despliegue, po4a compila un compendio temporal durante la actualización de PO, para compartir las traducciones entre todos los ficheros 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 ficheros PO que contengan está cadena. Cuando no quede difuso por el traductor, la traducción es utilizada automáticamente en cada fichero PO.

Especificar los documentos a traducir

Además debe alistar los documentos que serían traducidos. Por cada fichero maestro, debe especificar el formato del intérprete a utilizar, la ubicación de documento traducido para producir, y opcionalmente alguna configuración. Aquí hay un ejemplo:

 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
              de:doc/de/mein_kram.sgml
[type: man] script fr:doc/fr/script.1 de:doc/de/script.1
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             de:doc/de/script.xml

Pero de nuevo, estas líneas complejas son difíciles para leer y modificar, p. ej. cuando agregue un idioma nuevo. Es mucho más fácil reorganizar cosas empleando la plantilla $lang como sigue:

 [type: sgml]    doc/mi_material.sgml $lang:doc/$lang/mi_material.sgml
 [type: man]     script.1          $lang:po/$lang/script.1
 [type: docbook] doc/script.xml    $lang:doc/$lang/script.xml

Especificar opciones

Hay dos tipos de opciones: opciones po4a son valores predeterminados para las opciones de línea de orden po4a mientras que opciones de formato son utilizadas para cambiar el comportamiento de los intérpretes del formato. Como una opciones de po4a, pudo por ejemplo especificar en su fichero de configuración que el valor predeterminado del parámetro de línea de orden --keep es un 50% en vez de un 80%. Las opciones de formato están documentadas en una página específica de cada módulo de intérprete, p.ej. Locale::Po4a::Xml(3pm). Pudo por ejemplo aprobar nostrip al intérprete XML para no recortar los espacios alrededor de las cadenas extraídas. Puede pasar estas opciones para un fichero maestro específico, o incluso para una traducción específica de ese fichero, utilizando "opt:" y "opt_XX:" para el idioma "XX". En el ejemplo siguiente, la opción nostrip es pasada al intérprete XML (para todos los idiomas), mientras que el umbral será reducido a 0% para la traducción francesa (que es por lo tanto siempre conservada).

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_es:"--keep 0"

En cualquier caso, estos segmentos de configuración deben estar ubicados al final de la línea. La declaración de ficheros deben primero venir, después el adjunto si hay alguno (vea debajo), y después solamente las opciones. El agrupamiento de configuración de segmentos no es muy importante, debido a que los elementos están concatenados internamente como cadenas. Los siguientes ejemplos son todos equivalentes:

  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_es:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_es:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_es:--keep opt_es:0

Anote que las opciones específicas del idioma no son utilizadas cuando crea el fichero POT. Es por ejemplo imposible aprobar nostrip al intérprete solamente cuando construya la traducción francesa, porque el mismo fichero POT es utilizado para actualizar cada idioma. Por tanto las opciones solamente que pueda ser específicas del idioma son las que son utilizadas cuando produce la traducción, como la opción "--keep". Configuración de aliases Para aprobar las mismas opciones a varios ficheros, lo mejor es definir un tipo alias como sigue. En el ejemplo siguiente, "--keep 0" es pasado a cada traducción italiana utilizando este tipo "test", que es una extensión del tipo "man".

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

También puede extender un tipo existente reutilizando el mismo nombre para el alias tal como sigue. Esto no es interpretado como una definición recursiva errónea.

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

Opciones predeterminadas globales Además puede utilizar líneas de "[opciones]" para definir opciones que deben ser empleadas para todos los ficheros, independientemente de su tipo.

  [opciones] --keep 20 --option sin-tira

Como con las opciones de línea de orden, puede abreviar los parámetros pasados dentro del fichero de configuración:

  [opciones] -k 20 -o nostrip

Opciones prioritarias Las opciones de cada fuente están concatenadas, asegurando que los valores predeterminados puedan ser fácilmente anulados por opciones más específicas. El pedido es como sigue:

•

Las "[opciones]" de líneas proporciona valores predeterminados que pueden ser anuladas por cualquier otro origen.

•

Tipo de aliases estarán cuando necesite. Parámetros específicos del idioma anula los aplicables a todos los idiomas.

•

Los parámetros que son específicos a un fichero maestro dado anula ambos predeterminados y los que vengan desde el tipo alias. En este caso también, los parámetros específicos del idioma anulan los globales.

•

Finalmente, los parámetros proporcionado en la línea de orden po4a supera cualquiera de los parámetros desde el fichero de configuración.

Ejemplo Aquí hay un ejemplo mostrando como entrecomillas los espacios y entrecomillados:

 [po_directory] man/po/
 
 [opciones] --master-charset UTF-8
 
 [po4a_alias:man] man opt:"-o \"mdoc=NOMBRE,VEA ADEMÁS\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_es:"-L UTF-8" opt_es:--verbose

Apéndice: Añadiendo contenido adicional en la traducción

Si desea agregar una sección adicional a la traducción, por ejemplo para proporcionar reconocimiento a los traductores, entonces necesita definir un addendum a la línea definiendo su fichero maestro. Refiérase a la página po4a(7) para más detalles en la sintaxis de ficheros addendum.

 [type: pod] script es:doc/es/script.1 \
             add_es:doc/l10n/script.es.add

Además puede emplear plantillas del idioma como sigue:

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

Si falla un addendum al aplicar, la traducción es descartada. Modificadores para declaración de addendum Modificadores de adjuntos pueden simplificar la configuración del fichero dentro del caso donde ninguno de los idioma proporciona un adjunto o cuando el listado de los adjuntos cambia desde un idioma al otro. El modificador es un carácter único localizado antes del nombre del fichero.

?

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.

Lo siguiente incluye un adjunto dentro de cualquier idioma, pero si solamente existe. No se comunica un error si el adjunto no existe.

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

Lo siguiente incluye un listado de adjuntos por cada idioma:

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

Filtrar las cadenas traducidas

A veces, desea ocultar algunos segmentos desde el proceso de traducción. Para eso extender, puede proporcionar un parámetro "pot_in" a su fichero maestro para especificar el nombre del fichero a utilizar en lugar del maestro real cuando compile el fichero POT. Aquí hay un ejemplo:

  [type:docbook] libro.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

Con este parámetro, los segmentos a traducir serán extraídos desde el libro.filtrado.xml (ese debe ser generado antes de invocar po4a) mientras los ficheros traducidos serán compilados desde libro.xml. Como un resultado, cualquier segmento que es parte de libro.xml pero no está dentro del libro-filtrado.xml no será incluido dentro de los ficheros PO, impidiendo a los traductores desde proporionar una traducción para ellos. Por tanto estos segmentos serán dejados sin modificar cuando produzca los documentos traducidos. Esto naturalmente decrementa el nivel de traducción, por lo que quizá necesita la opción "--keep" para asegurar que el documento es generado a pesar de todo.

VÉASE TAMBIÉN

po4a-gettextize(1), po4a(7).

AUTORES

 Denis Barbier <[email protected]>
 Nicolas François <[email protected]>
 Martin Quinson (mquinson#debian.org)

TRADUCCION

 Jordi Vilalta <[email protected]>
 Omar Campagne <[email protected]>

DERECHO DE COPIA Y LICENCIA

Copyright 2002-2022 by SPI, inc. Esto es software libre; puede redistribuirlo y/o modificarlo bajo las condiciones de la licencia GPL (consulte el fichero COPYING).