Provided by: po4a_0.41-1ubuntu1_all bug

NOMBRE

       Locale::Po4a::Po - Modulo para la manipulacion de ficheros PO

SINOPSIS

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

           # Leer el fichero PO
           $pofile->read('fichero.po');

           # Anadir una entrada
           $pofile->push('msgid' => 'Hello', 'msgstr' => 'hola',
                         'flags' => "wrap", 'reference'=>'file.c:46');

           # Extraer una traduccion
           $pofile->gettext("Hello"); # devuelve 'Hola'

           # Escribir el resultado en un fichero
           $pofile->write('otrofichero.po');

DESCRIPCI'ON

       Locale::Po4a::Po es un modulo que permite manipular catalogos de
       mensajes. Con el puede leer y escribir desde/a un fichero (cuya
       extension es a menudo po), puede crear nuevas entradas sobre en el
       momento o pedir la traduccion de una cadena.

       Para una descripcion mas completa de los catalogos de mensajes en
       formato PO y su uso, consulte la documentacion del programa gettext.

       Este modulo es parte del proyecto PO4A, cuyo objetivo es usar ficheros
       PO (disenados originalmente para facilitar la traduccion de mensajes de
       programa) para traducir de todo, incluyendo documentacion (paginas de
       manual, manuales info), descripciones de paquetes, plantillas debconf,
       y cualquier cosa que se pueda beneficiar de esto.

OPCIONES ACEPTADAS POR ESTE MODULO

       porefs
           Esto especifica el formato de referencia. Puede usar none, para no
           producir ninguna referencia, noline para no especificar el numero
           de la linea, y full para incluir referencias completas.

Funciones sobre el cat'alogo de mensajes entero

       new()
           Crea un nuevo catalogo de mensajes. Si se introduce un argumento,
           este sera el nombre del fichero PO a cargar.

       read($)
           Lee un fichero PO (cuyo nombre se introduce como argumento). Las
           entradas anteriormente existentes no se eliminan, las nuevas se
           anaden al final del catalogo.

       write($)
           Escribe el catalogo actual al fichero dado.

       write_if_needed($$)
           Al igual que <<write>>, pero si el fichero PO o POT ya existe, el
           objeto se escribira en un fichero temporal para su comparacion con
           el fichero existente, y asi determinar si precisa una actualizacion
           (esto evita modificar el POT para solo actualizar una linea de
           referencia o el campo <<POT-Creation-Date>>)

       gettextize($$)
           Esta funcion produce un catalogo de mensajes traducidos desde dos
           catalogos, el original y su traduccion. Este proceso se describe en
           la seccion de po4a(7) Gettextizaci'on: 'cc'omo funciona?.

       filter($)
           Esta funcion extrae un catalogo desde uno existente. Solo se
           colocan en el catalogo resultante las entradas que tengan una
           referencia en el fichero dado.

           Esta funcion analiza su argumento, lo convierte en una definicion
           de una funcion de Perl, la pasa por <<eval>> y filtra los campos
           por los que esta funcion devuelve verdadero (<<true>>).

           A veces me encanta Perl ;)

       to_utf8()
           Recodifica los msgtr del PO a UTF-8. No hace nada si el juego de
           caracteres no esta especificado en el fichero PO (valor
           <<CHARSET>>), o si ya esta en UTF-8 o ASCII.

Funciones para usar un cat'alogo de mensajes para traducciones

       gettext($%)
           Solicita la traduccion de la cadena dada como argumento en el
           catalogo actual. La funcion devuelve la cadena original (sin
           traducir) si no se ha encontrado la cadena.

           Despues de la cadena a traducir, puede pasar una serie asociativa
           (<<hash>>) de argumentos adicionales. Aqui estan las entradas
           validas:

           wrap
               Booleano que indica si se puede considerar que los espacios
               blancos de la cadena son irrelevantes. De ser asi, la funcion
               canoniza la cadena antes de buscar su traduccion, y justifica
               el resultado.

           wrapcol
               La columna en la que se debe hacer el salto de linea (por
               omision: 76).

       stats_get()
           Devuelve estadisticas sobre la tasa de aciertos de gettext desde la
           ultima vez que se invoco <<stats_clear()>>. Cabe destacar que estas
           no son las mismas estadisticas que muestra <<msgfmt --statistic>>.
           Estas son sobre el uso reciente del fichero PO, mientras que msgfmt
           informa del estado del fichero. Ejemplo de uso:

               [algun uso del fichero PO para traducir cosas]

               ($percent,$hit,$queries) = $pofile->stats_get();
               print "Hasta el momento hemos encontrado traducciones para el $percent\%  ($hit of $queries) de cadenas.\n";

       stats_clear()
           Limpia las estadisticas de aciertos de gettext.

Funciones para construir un cat'alogo de mensajes

       push(%)
           Inserta una nueva entrada al final del catalogo actual. Los
           argumentos deberian formar una tabla de elementos asociativos
           (<<hash>>). Las claves validas son:

           msgid
               La cadena en el idioma original.

           msgstr
               La traduccion.

           reference
               Una indicacion de donde se encontro la cadena. Ejemplo:
               <<fichero.c:46>> (significa en la linea 46 del 'fichero.c').
               Puede ser una lista separada por espacios en caso de multiples
               apariciones.

           comment
               Un comentario anadido aqui manualmente (por los traductores).
               El formato aqui es libre.

           automatic
               Un comentario que anadio automaticamente el programa de
               extraccion de cadenas. Consulte la opcion --add-comments del
               programa xgettext para mas informacion.

           flags
               Lista separada por espacios de todas la marcas (<<flags>>)
               definidas para esta entrada.

               Las marcas validas 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.

               Consulte la documentacion de gettext para conocer sus
               significados.

           type
               Este es principalmente un parametro interno: se usa cuando se
               gettextizan documentos. La idea aqui es analizar el original y
               la traduccion en un objeto PO, y fusionarlos, usando el msgid
               de uno como msgid y el msgid del otro como msgstr. Para
               asegurarnos de 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 demas en DocBook). Si los tipos de las
               cadenas no coinciden, significa que ambos ficheros no tienen la
               misma estructura, y el proceso devuelve un error.

               Esta informacion se escribe como un comentario automatico en el
               fichero 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 cosmeticos. Si es verdadero, la cadena
               se canoniza antes de su uso.

               Esta informacion se escribe en el fichero PO usando las marcas
               wrap o no-wrap.

           wrapcol
               La columna en la que se debe hacer el salto de linea (por
               omision: 76).

               Esta informacion no se escribe en el fichero PO.

Funciones varias

       count_entries()
           Devuelve el numero de entradas del catalogo (sin la cabecera)

       count_entries_doc()
           Devuelve el numero de entradas del documento. Si una cadena aparece
           varias veces en el documento, se contara varias veces.

       msgid($)
           Devuelve el msgid con el numero dado.

       msgid_doc($)
           Devuelve el msgid y su posicion en el documento.

       get_charset()
           Devuelve el juego de caracteres especificado en la cabecera PO. Si
           no se le ha dado valor, devuelve <<CHARSET>>.

       set_charset($)
           Esto define el juego de caracteres de la cabecera PO con el valor
           especificado en su primer argumento. Si nunca invoca esta funcion
           (y no se carga ningun fichero con un juego de caracteres
           especificado), el valor predefinido es <<CHARSET>>. Este valor no
           cambia el comportamiento del modulo, 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)