Provided by: po4a_0.34-2_all bug

NOMBRE

       Locale::Po4a::Po - mA~Xdulo para manipulaciA~Xn de archivos po

SINOPSIS

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

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

           # Add an entry
           $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                         'flags' => "wrap", 'reference'=>'file.c:46');

           # Extraer una traducciA~Xn
           $archivopo->gettext("Hello"); # devuelve 'Hola'

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

DESCRIPCION

       Locale::Po4a::Po es un mA~Xdulo que permite manejar catA~Xlogos de
       mensajes. Con A~Xl puedes leer y escribir desde/a un archivo (cuya
       extensiA~Xn es a menudo po), puedes crear nuevas entradas sobre la
       marcha o pedir la traducciA~Xn de una cadena.

       Para una descripciA~Xn mA~Xs completa de los catA~Xlogos de mensajes de
       los archivos po y su uso, consulta la documentaciA~Xn del programa
       gettext.

       Este mA~Xdulo es parte del proyecto PO4A, cuyo objetivo es usar
       archivos po (diseA~Xados originalmente para facilitar la traducciA~Xn
       de mensajes de programa) para traducir de todo, incluyendo
       documentaciA~Xn (pA~Xginas 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 catA~Xlogo de mensajes entero

       new()
           Crea un nuevo catA~Xlogo de mensajes. Si se proporciona un
           parA~Xmetro, este serA~X el nombre del archivo po a cargar.

       read($)
           Lee un archivo po (cuyo nombre se pasa como parA~Xmetro).  Las
           entradas anteriormente existentes no se eliminan, las nuevas se
           aA~Xaden al final del catA~Xlogo.

       write($)
           Escribe el catA~Xlogo 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 funciA~Xn produce un catA~Xlogo de mensajes traducido desde
           dos catA~Xlogos, uno original y otro, su traducciA~Xn. Este proceso
           se describe en la secciA~Xn GettextizaciA~Xn: cA~Xmo funciona? de
           po4a(7).

       filter($)
           Esta funciA~Xn extrae un catA~Xlogo desde uno existente. SA~Xlo se
           colocan en el catA~Xlogo resultante las entradas que tengan una
           referencia en el fichero dado.

           Esta funciA~Xn analiza su parA~Xmetro, lo convierte en una
           definiciA~Xn de una funciA~Xn de perl, la evalua y filtra los
           campos por los que esta funciA~Xn 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 estA~X especificado en el fichero po (valor
           "CHARSET"), o si ya estA~X en utf-8 o ascii.

Funciones para usar un catA~Xlogo de mensajes para traducciones

       gettext($%)
           Solicita la traducciA~Xn de la cadena dada como parA~Xmetro en el
           catA~Xlogo actual.  La funciA~Xn devuelve la cadena original (sin
           traducir) si no se ha encontrado la cadena.

           DespuA~Xs de la cadena a traducir, puedes pasar un hash de
           parA~Xmetros extra. AquA~ hay las entradas vA~Xlidas:

           wrap
               booleano que indica si se puede considerar que los espacios
               blancos de la cadena son irrelevantes. Si es cierto, la
               funciA~Xn canoniza la cadena antes de buscar su traducciA~Xn, y
               justifica el resultado.

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

       stats_get()
           Devuelve estadA~sticas sobre la tasa de aciertos de gettext desde
           la A~Xltima vez que se llamA~X stats_clear(). Cabe destacar que
           A~Xstas no son las mismas estadA~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:

               [algA~Xn 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 estadA~sticas sobre aciertos de gettext.

Funciones para construir un catA~Xlogo de mensajes

       push(%)
           Insertar una nueva entrada al final del catA~Xlogo actual. Los
           parA~Xmetros deben formar una tabla de hash. Las claves vA~Xlidas
           son:

           msgid
               la cadena en el idioma original.

           msgstr
               la traducciA~Xn.

           reference
               una indicaciA~Xn de dA~Xnde se encontrA~X la cadena. Ejemplo:
               archivo.c:46 (significado en ’archivo.c’ en la lA~nea 46).
               Puede ser una lista separada por espacios en caso de
               mA~Xltiples ocurrencias.

           comment
               un comentario aA~Xadido aquA~ manualmente (por los
               traductores). El formato aquA~ es libre

           automatic
               un comentario que aA~XadiA~X automA~Xticamente el programa de
               extracciA~Xn de cadenas. Ver la opciA~Xn --add-comments del
               programa xgettext para mA~Xs informaciA~Xn.

           flags
               lista de todos los flags definidos para A~Xsta entrada
               separados por espacios.

               Los flags vA~Xlidos 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 documentaciA~Xn de gettext para conocer sus
               significados.

           type
               Este es principalmente un parA~Xmetro interno: es usado
               mientras se gettextizan un documentos. La idea aquA~ es
               analizar el original y la traducciA~Xn 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 demA~Xs 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 informaciA~Xn se escribe como un comentario automA~Xtico
               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 cosmA~Xticos. Si es cierto, la cadena
               es canonizada antes de usar.

               Esta informaciA~Xn 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 lA~nea (defecto:
               76).

               Esta informaciA~Xn no se escribe en el archivo po.

Funciones varias

       count_entries()
           Devuelve el nA~Xmero de entradas del catA~Xlogo (sin la cabecera)

       count_entries_doc()
           Returns the number of entries in document. If a string appears
           multiple times in the document, it will be counted multiple times

       msgid($)
           Devuelve el msgid del nA~Xmero dado.

       msgid_doc($)
           Returns the msgid with the given position in the document.

       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 parA~Xmetro. Si nunca se le da valor (y
           no se carga ningA~Xn fichero con un juego de caracteres
           especificado), el valor por defecto se deja en "CHARSET". Este
           valor no cambia el comportamiento del mA~Xdulo, 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>