Provided by: po4a_0.23-1_all bug

NOMBRE

       Locale::Po4a::Po - módulo para manipulación de archivos po

SINOPSIS

           use Locale::Po4a::Po;
           my $archivopo=Locale::Po4a::Po->new();

           # Read po file
           $pofile->read(’file.po’);

           # Añadir una entrada
           $archivopo->push(’msgid’ => ’Hello’, ’msgstr’ => ’Hola’,
                         ’flags’ => "wrap", ’reference’=>’archivo.c:46’);

           # Extraer una traducción
           $archivopo->gettext("Hello"); # devuelve ’Hola’

           # Escribir el resultado en un archivo
           $archivopo->write(’otroarchivo.po’);

DESCRIPCION

       Locale::Po4a::Po es un módulo que permite manejar catálogos de
       mensajes. Con él puedes leer y escribir desde/a un archivo (cuya
       extensión es a menudo po), puedes crear nuevas entradas sobre la marcha
       o pedir la traducción de una cadena.

       Para una descripción más completa de los catálogos de mensajes de los
       archivos po y su uso, consulta la documentación del programa gettext.

       Este módulo es parte del proyecto PO4A, cuyo objetivo es usar archivos
       po (diseñados originalmente para facilitar la traducción de mensajes de
       programa) para traducir de todo, incluyendo documentación (páginas de
       manual, manuales info), descripciones de paquetes, plantillas debconf,
       y cualquier cosa que se pueda beneficiar de esto.

OPCIONES ACEPTADAS POR ESTE MODULO

       porefs
           This specifies the reference format. It can be one of ’none’ to not
           produce any reference, ’noline’ to not specify the line number, and
           ’full’ to include complete references.

Funciones sobre el catálogo de mensajes entero

           new()
               Crea un nuevo catálogo de mensajes. Si se proporciona un
               parámetro, este será el nombre del archivo po a cargar.

           read($)
               Lee un archivo po (cuyo nombre se pasa como parámetro).  Las
               entradas anteriormente existentes no se eliminan, las nuevas se
               añaden al final del catálogo.

           write($)
               Escribe el catálogo actual al archivo dado.

           write_if_needed($$)
               Like write, but if the PO or POT file already exists, the
               object will be written in a temporary file which will be
               compared with the existing file to check that the update is
               needed (this avoids to change a POT just to update a line
               reference or the POT-Creation-Date field).

           gettextize($$)
               Esta función produce un catálogo de mensajes traducido desde
               dos catálogos, uno original y otro, su traducción. Este proceso
               se describe en la sección Gettextizacin: cmo funciona? de
               po4a(7).

           filter($)
               Esta función extrae un catálogo desde uno existente. Sólo se
               colocan en el catálogo resultante las entradas que tengan una
               referencia en el fichero dado.

               Esta función analiza su parámetro, lo convierte en una
               definición de una función de perl, la evalua y filtra los
               campos por los que esta función devuelve cierto.

               A veces me encanta perl :)

           to_utf8()
               Recodifica los msgtrs del po a utf-8. No hace nada si el juego
               de caracteres no está especificado en el fichero po (valor
               "CHARSET"), o si ya está en utf-8 o ascii.

Funciones para usar un catálogo de mensajes para traducciones

       gettext($%)
           Solicita la traducción de la cadena dada como parámetro en el
           catálogo actual.  La función devuelve la cadena original (sin
           traducir) si no se ha encontrado la cadena.

           Después de la cadena a traducir, puedes pasar un hash de parámetros
           extra. Aquí hay las entradas válidas:

           wrap
               booleano que indica si se puede considerar que los espacios
               blancos de la cadena son irrelevantes. Si es cierto, la función
               canoniza la cadena antes de buscar su traducción, y justifica
               el resultado.

           wrapcol
               La columna en la que se debe hacer el salto de línea (defecto:
               76).

       stats_get()
           Devuelve estadísticas sobre la tasa de aciertos de gettext desde la
           última vez que se llamó stats_clear(). Cabe destacar que éstas no
           son las mismas estadísticas que muestra msgfmt --statistic. Estas
           son sobre el uso reciente del archivo po, mientras que msgfmt
           informa del estado del archivo.  Ejemplo de uso:

               [algún uso del archivo po para traducir cosas]

               ($porcentaje,$aciertos,$solicitudes) = $archivopo->stats_get();
               print "Hasta el momento hemos encontrado traducciones para el $porcentaje\%  ($aciertos de $solicitudes) de cadenas.\n";

       stats_clear()
           Limplia las estadísticas sobre aciertos de gettext.

Funciones para construir un catálogo de mensajes

       push(%)
           Insertar una nueva entrada al final del catálogo actual. Los
           parámetros deben formar una tabla de hash. Las claves válidas son:

           msgid
               la cadena en el idioma original.

           msgstr
               la traducción.

           reference
               una indicación de dónde se encontró la cadena. Ejemplo:
               archivo.c:46 (significado en ’archivo.c’ en la línea 46). Puede
               ser una lista separada por espacios en caso de múltiples
               ocurrencias.

           comment
               un comentario añadido aquí manualmente (por los traductores).
               El formato aquí es libre

           automatic
               un comentario que añadió automáticamente el programa de
               extracción de cadenas. Ver la opción --add-comments del
               programa xgettext para más información.

           flags
               lista de todos los flags definidos para ésta entrada separados
               por espacios.

               Los flags válidos son: c-text, python-text, lisp-text,
               elisp-text, librep-text, smalltalk-text, java-text, awk-text,
               object-pascal-text, ycp-text, tcl-text, wrap, no-wrap y fuzzy.

               Ver la documentación de gettext para conocer sus significados.

           type
               Este es principalmente un parámetro interno: es usado mientras
               se gettextizan un documentos. La idea aquí es analizar el
               original y la traducción en un objeto po, y mezclarlos, usando
               el msgid de uno como msgid y el msgid del otro como msgstr.
               Para asegurarnos que todo va bien, a cada msgid de los objetos
               po se le da un tipo, basado en su estructura (como "chapt",
               "sect1", "p" y demás en docbook). Si los tipos de las cadenas
               no coinciden, significa que ambos archivos no tienen la misma
               estructura, y el proceso comunica un error.

               Esta información se escribe como un comentario automático en el
               archivo po, ya que informa al traductor del contexto de la
               cadena a traducir.

           wrap
               booleano que indica si los espacios en blanco se pueden
               manipular en reformateos cosméticos. Si es cierto, la cadena es
               canonizada antes de usar.

               Esta información se escribe en el archivo po usando los flags
               ’wrap’ o ’no-wrap’.

           wrapcol
               La columna en la que se debe hacer el salto de línea (defecto:
               76).

               Esta información no se escribe en el archivo po.

Funciones varias

       count_entries()
           Devuelve el número de entradas del catálogo (sin la cabecera)

       msgid($)
           Devuelve el msgid del número dado.

       get_charset()
           Esto devuelve el juego de caracteres especificado en la cabecera
           po. Si no se le ha dado valor, devuelve "CHARSET".

       set_charset($)
           Esto ajusta el juego de caracteres de la cabecera po al valor
           especificado en su primer parámetro. Si nunca se le da valor (y no
           se carga ningún fichero con un juego de caracteres especificado),
           el valor por defecto se deja en "CHARSET". Este valor no cambia el
           comportamiento del módulo, simplemente se usa para llenar el campo
           de la cabecera, y para devolverlo en get_charset().

AUTORES

        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#debian.org)

TRADUCCION

        Jordi Vilalta <jvprat@gmail.com>