Unix/Linux Go Back    


CentOS 7.0 - man page for locale::po4a::po (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Locale::Po4a::Po(3)	       User Contributed Perl Documentation	      Locale::Po4a::Po(3)

NAME
       Locale::Po4a::Po - PO file manipulation module

SYNOPSIS
	   use Locale::Po4a::Po;
	   my $pofile=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');

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

	   # Write back to a file
	   $pofile->write('otherfile.po');

DESCRIPTION
       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 documentation of the gettext program.

       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.

OPTIONS ACCEPTED BY THIS MODULE
       porefs type[,wrap|nowrap]
	   Specify the reference format. Argument type can be one of none to not produce any
	   reference, noline to not specify the line number (more accurately all line numbers are
	   replaced by 1), counter to replace line number by an increasing counter, and full to
	   include complete references.

	   Argument can be followed by a comma and either wrap or nowrap keyword.  References are
	   written by default on a single line.  The wrap option wraps references on several
	   lines, to mimic gettext tools (xgettext and msgmerge).  This option will become the
	   default in a future release, because it is more sensible.  The nowrap option is
	   available so that users who want to keep the old behavior can do so.

       --msgid-bugs-address email@address
	   Set the report address for msgid bugs. By default, the created POT files have no
	   Report-Msgid-Bugs-To fields.

       --copyright-holder string
	   Set the copyright holder in the POT header. The default value is "Free Software
	   Foundation, Inc."

       --package-name string
	   Set the package name for the POT header. The default is "PACKAGE".

       --package-version string
	   Set the package version for the POT header. The default is "VERSION".

Functions about whole message catalogs
       new()
	   Creates a new message catalog. If an argument is provided, it's the name of a PO file
	   we should load.

       read($)
	   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.

       write($)
	   Writes the current catalog to the given file.

       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 if the update is
	   needed (this avoids to change a POT just to update a line reference or the POT-
	   Creation-Date field).

       gettextize($$)
	   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?.

       filter($)
	   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 ;)

       to_utf8()
	   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
       gettext($%)
	   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:

	   wrap
	       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.

	   wrapcol
	       the column at which we should wrap (default: 76).

       stats_get()
	   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";

       stats_clear()
	   Clears the statistics about gettext hits.

Functions to build a message catalog
       push(%)
	   Push a new entry at the end of the current catalog. The arguments should form a hash
	   table. The valid keys are:

	   msgid
	       the string in original language.

	   msgstr
	       the translation.

	   reference
	       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.

	   comment
	       a comment added here manually (by the translators). The format here is free.

	   automatic
	       a comment which was automatically added by the string extraction program. See the
	       --add-comments option of the xgettext program for more information.

	   flags
	       space-separated list of all defined flags for this entry.

	       Valid flags are: 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 and fuzzy.

	       See the gettext documentation for their meaning.

	   type
	       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.

	   wrap
	       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.

	   wrapcol
	       the column at which we should wrap (default: 76).

	       This information is not written to the PO file.

Miscellaneous functions
       count_entries()
	   Returns the number of entries in the catalog (without the header).

       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($)
	   Returns the msgid of the given number.

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

       get_charset()
	   Returns the character set specified in the PO header. If it hasn't been set, it will
	   return "CHARSET".

       set_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().

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

perl v5.16.3				    2014-06-10			      Locale::Po4a::Po(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:50 PM.