.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Locale::PO 3pm"
.TH Locale::PO 3pm "2014-05-29" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Locale::PO \- Perl module for manipulating .po entries from GNU gettext
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Locale::PO;
\&
\&    $po = new Locale::PO([\-option=>value,...])
\&    [$string =] $po\->msgid([new string]);
\&    [$string =] $po\->msgstr([new string]);
\&    [$string =] $po\->comment([new string]);
\&    [$string =] $po\->automatic([new string]);
\&    [$string =] $po\->reference([new string]);
\&    [$value =] $po\->fuzzy([value]);
\&    [$value =] $po\->add_flag(\*(Aqc\-format\*(Aq);
\&    print $po\->dump;
\&
\&    $quoted_string = $po\->quote($string);
\&    $string = $po\->dequote($quoted_string);
\&
\&    $aref = Locale::PO\->load_file_asarray(<filename>,[encoding]);
\&    $href = Locale::PO\->load_file_ashash(<filename>,[encoding]);
\&    Locale::PO\->save_file_fromarray(<filename>,$aref,[encoding]);
\&    Locale::PO\->save_file_fromhash(<filename>,$href,[encoding]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module simplifies management of \s-1GNU\s0 gettext .po files and is an
alternative to using emacs po-mode. It provides an object-oriented
interface in which each entry in a .po file is a Locale::PO object.
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "new"
.Vb 2
\&    my Locale::PO $po = new Locale::PO;
\&    my Locale::PO $po = new Locale::PO(%options);
.Ve
.Sp
Create a new Locale::PO object to represent a po entry.
You can optionally set the attributes of the entry by passing
a list/hash of the form:
.Sp
.Vb 1
\&    \-option=>value, \-option=>value, etc.
.Ve
.Sp
Where options are msgid, msgid_plural, msgstr, msgctxt, comment, automatic,
reference, fuzzy_msgctxt, fuzzy_msgid, fuzzy_msgid_plural,
fuzzy, and c\-format. See accessor methods below.
.Sp
To generate a po file header, add an entry with an empty
msgid, like this:
.Sp
.Vb 8
\&    $po = new Locale::PO(\-msgid=>\*(Aq\*(Aq, \-msgstr=>
\&            "Project\-Id\-Version: PACKAGE VERSION\e\en" .
\&            "PO\-Revision\-Date: YEAR\-MO\-DA HO:MI +ZONE\e\en" .
\&            "Last\-Translator: FULL NAME <EMAIL@ADDRESS>\e\en" .
\&            "Language\-Team: LANGUAGE <LL@li.org>\e\en" .
\&            "MIME\-Version: 1.0\e\en" .
\&            "Content\-Type: text/plain; charset=CHARSET\e\en" .
\&            "Content\-Transfer\-Encoding: ENCODING\e\en");
.Ve
.IP "msgid" 4
.IX Item "msgid"
Set or get the untranslated string from the object.
.Sp
This method expects the new string in unquoted form but returns the current string in quoted form.
.IP "msgid_plural" 4
.IX Item "msgid_plural"
Set or get the untranslated plural string from the object.
.Sp
This method expects the new string in unquoted form but returns the current string in quoted form.
.IP "msgstr" 4
.IX Item "msgstr"
Set or get the translated string from the object.
.Sp
This method expects the new string in unquoted form but returns the current string in quoted form.
.IP "msgstr_n" 4
.IX Item "msgstr_n"
Get or set the translations if there are purals involved. Takes and
returns a hashref where the keys are the 'N' case and the values are
the strings. eg:
.Sp
.Vb 6
\&    $po\->msgstr_n(
\&        {
\&            0 => \*(Aqfound %d plural translations\*(Aq,
\&            1 => \*(Aqfound %d singular translation\*(Aq,
\&        }
\&    );
.Ve
.Sp
This method expects the new strings in unquoted form but returns the current strings in quoted form.
.IP "msgctxt" 4
.IX Item "msgctxt"
Set or get the translation context string from the object.
.Sp
This method expects the new string in unquoted form but returns the current string in quoted form.
.IP "fuzzy_msgid" 4
.IX Item "fuzzy_msgid"
Set or get the outdated untranslated string from the object.
.Sp
This method expects the new string in unquoted form but returns the current string in quoted form.
.IP "fuzzy_msgid_plural" 4
.IX Item "fuzzy_msgid_plural"
Set or get the outdated untranslated plural string from the object.
.Sp
This method expects the new string in unquoted form but returns the current string in quoted form.
.IP "fuzzy_msgctxt" 4
.IX Item "fuzzy_msgctxt"
Set or get the outdated translation context string from the object.
.Sp
This method expects the new string in unquoted form but returns the current string in quoted form.
.IP "obsolete" 4
.IX Item "obsolete"
Returns 1 if the entry is obsolete.
Obsolete entries have their msgid, msgid_plural, msgstr, msgstr_n and msgctxt lines commented out with \*(L"#~\*(R"
.Sp
When using load_file_ashash, non-obsolete entries will always replace obsolete entries with the same msgid.
.IP "comment" 4
.IX Item "comment"
Set or get translator comments from the object.
.Sp
If there are no such comments, then the value is undef.  Otherwise,
the value is a string that contains the comment lines delimited with
\&\*(L"\en\*(R".  The string includes neither the \*(L"#\ \*(R" at the beginning of
each comment line nor the newline at the end of the last comment line.
.IP "automatic" 4
.IX Item "automatic"
Set or get automatic comments from the object (inserted by
emacs po-mode or xgettext).
.Sp
If there are no such comments, then the value is undef.  Otherwise,
the value is a string that contains the comment lines delimited with
\&\*(L"\en\*(R".  The string includes neither the \*(L"#.\ \*(R" at the beginning of
each comment line nor the newline at the end of the last comment line.
.IP "reference" 4
.IX Item "reference"
Set or get reference marking comments from the object (inserted
by emacs po-mode or gettext).
.IP "fuzzy" 4
.IX Item "fuzzy"
Set or get the fuzzy flag on the object (\*(L"check this translation\*(R").
When setting, use 1 to turn on fuzzy, and 0 to turn it off.
.IP "c_format" 4
.IX Item "c_format"
Set or get the c\-format or no-c-format flag on the object.
.Sp
This can take 3 values:
1 implies c\-format, 0 implies no-c-format, and undefined implies neither.
.IP "php_format" 4
.IX Item "php_format"
Set or get the php-format or no-php-format flag on the object.
.Sp
This can take 3 values:
1 implies php-format, 0 implies no-php-format, and undefined implies neither.
.IP "has_flag" 4
.IX Item "has_flag"
.Vb 3
\&    if ($po\->has_flag(\*(Aqperl\-format\*(Aq)) {
\&            ...
\&    }
.Ve
.Sp
Returns true if the flag exists in the entry's #~ comment
.IP "add_flag" 4
.IX Item "add_flag"
.Vb 1
\&    $po\->add_flag(\*(Aqperl\-format\*(Aq);
.Ve
.Sp
Adds the flag to the #~ comment
.IP "remove_flag" 4
.IX Item "remove_flag"
.Vb 1
\&    $po\->remove_flag(\*(Aqperl\-format\*(Aq);
.Ve
.Sp
Removes the flag from the #~ comment
.IP "loaded_line_number" 4
.IX Item "loaded_line_number"
When using one of the load_file_as* methods,
this will return the line number that the entry started at in the file.
.IP "dump" 4
.IX Item "dump"
Returns the entry as a string, suitable for output to a po file.
.IP "quote" 4
.IX Item "quote"
Applies po quotation rules to a string, and returns the quoted
string. The quoted string will have all existing double-quote
characters escaped by backslashes, and will be enclosed in double
quotes.
.IP "dequote" 4
.IX Item "dequote"
Returns a quoted po string to its natural form.
.IP "load_file_asarray" 4
.IX Item "load_file_asarray"
Given the filename of a po-file, reads the file and returns a
reference to a list of Locale::PO objects corresponding to the contents of
the file, in the same order.  Accepts an optional encoding parameter (e.g.
\&\*(L"utf8\*(R") which defines how the po-file's input stream will be configured.
.IP "load_file_ashash" 4
.IX Item "load_file_ashash"
Given the filename of a po-file, reads the file and returns a
reference to a hash of Locale::PO objects corresponding to the contents of
the file. The hash keys are the untranslated strings, so this is a cheap
way to remove duplicates. The method will prefer to keep entries that
have been translated.  Accepts an optional encoding parameter (e.g.
\&\*(L"utf8\*(R") which defines how the po-file's input stream will be configured.
.IP "save_file_fromarray" 4
.IX Item "save_file_fromarray"
Given a filename and a reference to a list of Locale::PO objects,
saves those objects to the file, creating a po-file.  Accepts an optional
encoding parameter (e.g. \*(L"utf8\*(R") which defines how the po-file's output
stream will be configured.
.IP "save_file_fromhash" 4
.IX Item "save_file_fromhash"
Given a filename and a reference to a hash of Locale::PO objects,
saves those objects to the file, creating a po-file. The entries
are sorted alphabetically by untranslated string.  Accepts an optional
encoding parameter (e.g. \*(L"utf8\*(R") which defines how the po-file's output
stream will be configured.
.SH "AUTHOR"
.IX Header "AUTHOR"
Maintainer: Ken Prows, perl@xev.net
.PP
Original version by: Alan Schwartz, alansz@pennmush.org
.SH "BUGS"
.IX Header "BUGS"
If you load_file_as* then save_file_from*, the output file may have slight
cosmetic differences from the input file (an extra blank line here or there).
.PP
msgid, msgid_plural, msgstr, msgstr_n and msgctxt expect a non-quoted string as input, but return quoted strings.
I'm hesitant to change this in fear of breaking the modules/scripts of people already using Locale::PO.
.PP
Locale::PO requires blank lines between entries, but Uniforum style \s-1PO\s0
files don't have any.
.PP
Please submit all bug requests using \s-1CPAN\s0's ticketing system.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIxgettext\fR\|(1).