Section: Strumenti Po4a (3pm)
Updated: 2018-12-10
Index Return to Main Contents


Locale::Po4a::Po - Modulo per la manipolazione di file PO  


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

    # Read PO file

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

    # Extract a translation
    $pofile->gettext("Hello"); # returns 'bonjour'

    # Write back to a file



Locale::Po4a::Po is a module that allows you to manipulate message catalogs. You can load and write from/to a file (which extension is often po), you can build new entries on the fly or request for the translation of a string.

For a more complete description of message catalogs in the PO format and their use, please refer to the info documentation of the gettext program (node ```PO Files''').

This module is part of the po4a project, which objective is to use PO files (designed at origin to ease the translation of program messages) to translate everything, including documentation (man page, info manual), package description, debconf templates, and everything which may benefit from this.  


--porefs type[,wrap|nowrap]
Specifica il formato di riferimento. L'argomento type può essere un valore qualsiasi tra: never per non produrre nessun riferimento, file per specificare solo il file senza il numero di riga, counter per rimpiazzare il numero di riga con un contatore incrementale, e full per includere il riferimento completo (valore predefinito: full).

L'argomento può essere seguito da una virgola e da una delle due parole chiave wrap o nowrap. I riferimenti, come impostazione predefinita, vengono scritti su una singola riga. L'opzione wrap manda a capo i riferimento su più righe, per emulare il comportamento degli strumenti di gettext (xgettext e msgmerge). Questa opzione diventerà predefinita in una versione futura, perchè è il comportamento più logico. L'opzione nowrap è disponibile per permettere agli utenti che lo desiderassero, di mantenere il vecchio comportamento.

--msgid-bugs-address indirizzo@email
Imposta l'indirizzo a cui inviare i rapporti di errore per i msgid. Come impostazione predefinita, i file POT creati non hanno campi Report-Msgid-Bugs-To.
--copyright-holder stringa
Imposta l'intestatario del copyright nell'intestazione del POT. Il valore predefinito è ``Free Software Foundation, Inc.''
--package-name stringa
Imposta il nome del pacchetto nell'intestazione del POT. Il valore predefinito è ``PACKAGE''.
--package-version stringa
Imposta la versione del pacchetto nell'intestazione del POT. Il valore predefinito è ``VERSION''.

Functions concerning entire message catalogs

Creates a new message catalog. If an argument is provided, it's the name of a PO file we should load.
Reads a PO file (which name is given as argument). Previously existing entries in self are not removed, the new ones are added to the end of the catalog.
Writes the current catalog to the given file.
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 if the update is needed (this avoids to change a POT just to update a line reference or the POT-Creation-Date field).
This function produces one translated message catalog from two catalogs, an original and a translation. This process is described in po4a(7), section Gettextization: how does it work?.
This function extracts a catalog from an existing one. Only the entries having a reference in the given file will be placed in the resulting catalog.

This function parses its argument, converts it to a Perl function definition, evals this definition and filters the fields for which this function returns true.

I love Perl sometimes ;)

Recodes to UTF-8 the PO's msgstrs. Does nothing if the charset is not specified in the PO file (``CHARSET'' value), or if it's already UTF-8 or ASCII.

Functions to use a message catalog for translations

Request the translation of the string given as argument in the current catalog. The function returns the original (untranslated) string if the string was not found.

After the string to translate, you can pass a hash of extra arguments. Here are the valid entries:

boolean indicating whether we can consider that whitespaces in string are not important. If yes, the function canonizes the string before looking for a translation, and wraps the result.
la colonna a cui andare a capo (valore predefinito: 76).
Returns statistics about the hit ratio of gettext since the last time that stats_clear() was called. Please note that it's not the same statistics than the one printed by msgfmt --statistic. Here, it's statistics about recent usage of the PO file, while msgfmt reports the status of the file. Example of use:

    [some use of the PO file to translate stuff]

    ($percent,$hit,$queries) = $pofile->stats_get();
    print "So far, we found translations for $percent\%  ($hit of $queries) of strings.\n";

Clears the statistics about gettext hits.

Functions to build a message catalog

Push a new entry at the end of the current catalog. The arguments should form a hash table. The valid keys are:
the string in original language.
the translation.
an indication of where this string was found. Example: file.c:46 (meaning in 'file.c' at line 46). It can be a space-separated list in case of multiple occurrences.
a comment added here manually (by the translators). The format here is free.
a comment which was automatically added by the string extraction program. See the --add-comments option of the xgettext program for more information.
space-separated list of all defined flags for this entry.

I flag validi sono: 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 e fuzzy.

Consultare la documentazione di gettext per conoscerne il significato.

this is mostly an internal argument: it is used while gettextizing documents. The idea here is to parse both the original and the translation into a PO object, and merge them, using one's msgid as msgid and the other's msgid as msgstr. To make sure that things get ok, each msgid in PO objects are given a type, based on their structure (like ``chapt'', ``sect1'', ``p'' and so on in DocBook). If the types of strings are not the same, that means that both files do not share the same structure, and the process reports an error.

This information is written as automatic comment in the PO file since this gives to translators some context about the strings to translate.

boolean indicating whether whitespaces can be mangled in cosmetic reformattings. If true, the string is canonized before use.

This information is written to the PO file using the wrap or no-wrap flag.

la colonna a cui andare a capo (valore predefinito: 76).

This information is not written to the PO file.


Miscellaneous functions

Returns the number of entries in the catalog (without the header).
Returns the number of entries in document. If a string appears multiple times in the document, it will be counted multiple times.
Returns ($uptodate, $diagnostic) with $uptodate indicating whether all msgid of the current po file are also present in the one passed as parameter (all other fields are ignored in the file comparison). Informally, if $uptodate returns false, then the po files would be changed when going through po4a-updatepo.

If $uptodate is false, then $diagnostic contains a diagnostic of why this is so.

Returns the msgid of the given number.
Returns the msgid with the given position in the document.
Returns the character set specified in the PO header. If it hasn't been set, it will return ``CHARSET''.
This sets the character set of the PO header to the value specified in its first argument. If you never call this function (and no file with a specified character set is read), the default value is left to ``CHARSET''. This value doesn't change the behavior of this module, it's just used to fill that field in the header, and to return it in get_charset().


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



 Danilo Piazzalunga <danilopiazza@libero.it>
 Marco Ciampa <ciampix@libero.it>



Functions concerning entire message catalogs
Functions to use a message catalog for translations
Functions to build a message catalog
Miscellaneous functions

This document was created by using the manual pages.
Time: 11:07:06 GMT, December 10, 2018
català Deutsch English español français Italiano 日本語 Bokmål polski Português Português (Brasil) Русский український 简体中文 (how to set the default document language)