blib::man::Po(3pm)

NOMBRE
Locale::Po4a::Po - modulo para manipulacion de archivos po

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

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

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

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

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

DESCRIPCION
Locale::Po4a::Po es un modulo que permite manejar catalogos de mensajes. Con el puedes leer y escribir desde/a un archivo (cuya extension es a menudo po), puedes crear nuevas entradas sobre la marcha o pedir la traduccion de una cadena.

Para una descripcion mas completa de los catalogos de mensajes de los archivos po y su uso, consulta la documentacion del programa gettext.

Este modulo es parte del proyecto PO4A, cuyo objetivo es usar archivos po (disen~ados 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
    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 catalogo de mensajes entero

new()
    Crea un nuevo catalogo de mensajes. Si se proporciona un parametro, este sera el nombre del archivo po a cargar.

read($)
    Lee un archivo po (cuyo nombre se pasa como parametro). Las entradas anteriormente existentes no se eliminan, las nuevas se an~aden al final del catalogo.

write($)
    Escribe el catalogo 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 funcion produce un catalogo de mensajes traducido desde dos catalogos, uno original y otro, su traduccion. Este proceso se describe en la seccion Gettextizacion: como funciona? de po4a(7).

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 parametro, lo convierte en una definicion de una funcion de perl, la evalua y filtra los campos por los que esta funcion 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 especificado en el fichero po (valor "CHARSET"), o si ya esta en utf-8 o ascii.

Funciones para usar un catalogo de mensajes para traducciones

gettext($%)
    Solicita la traduccion de la cadena dada como parametro 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, puedes pasar un hash de parametros extra. Aqui hay las entradas validas:

    wrap
        booleano que indica si se puede considerar que los espacios blancos de la cadena son irrelevantes. Si es cierto, 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 (defecto: 76).

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

        [algun 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 estadisticas sobre aciertos de gettext.

Funciones para construir un catalogo de mensajes

push(%)
    Insertar una nueva entrada al final del catalogo actual. Los parametros deben formar una tabla de 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: archivo.c:46 (significado en 'archivo.c' en la linea 46). Puede ser una lista separada por espacios en caso de multiples ocurrencias.

    comment
        un comentario an~adido aqui manualmente (por los traductores). El formato aqui es libre

    automatic
        un comentario que an~adio automaticamente el programa de extraccion de cadenas. Ver la opcion --add-comments del programa xgettext para mas informacion.

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

        Los flags validos 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 documentacion de gettext para conocer sus significados.

    type
        Este es principalmente un parametro interno: es usado mientras se gettextizan un documentos. La idea aqui es analizar el original y la traduccion 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 demas 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 informacion se escribe como un comentario automatico 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 cosmeticos. Si es cierto, la cadena es canonizada antes de usar.

        Esta informacion 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 linea (defecto: 76).

        Esta informacion no se escribe en el archivo po.

Funciones varias

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

msgid($)
    Devuelve el msgid del numero 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 parametro. Si nunca se le da valor (y no se carga ningun fichero con un juego de caracteres especificado), el valor por defecto se deja en "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)

TRADUCCION
 Jordi Vilalta <jvprat@gmail.com>

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 63:
    You forgot a '=back' before '=head1'