.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Po 3pm"
.TH Locale::Po4a::Po 3pm "2023-01-03" "Po4a Tools" "Po4a Tools"
.\" 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::Po4a::Po \- PO file manipulation module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Locale::Po4a::Po;
\&    my $pofile=Locale::Po4a::Po\->new();
\&
\&    # Read PO file
\&    $pofile\->read(\*(Aqfile.po\*(Aq);
\&
\&    # Add an entry
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aqbonjour\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # Extract a translation
\&    $pofile\->gettext("Hello"); # returns \*(Aqbonjour\*(Aq
\&
\&    # Write back to a file
\&    $pofile\->write(\*(Aqotherfile.po\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "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
\&\fIpo\fR), you can build new entries on the fly or request for the translation
of a string.
.PP
For a more complete description of message catalogs in the \s-1PO\s0 format and
their use, please refer to the info documentation of the gettext program (node \*(L"`\s-1PO\s0 Files\*(R"').
.PP
This module is part of the po4a project, which objective is to use \s-1PO\s0 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.
.SH "OPTIONS ACCEPTED BY THIS MODULE"
.IX Header "OPTIONS ACCEPTED BY THIS MODULE"
.IP "\fB\-\-porefs\fR \fItype\fR" 4
.IX Item "--porefs type"
Specify the reference format. Argument \fItype\fR can be one of \fBnever\fR
to not produce any reference, \fBfile\fR to only specify the file
without the line number, \fBcounter\fR to replace line number by an
increasing counter, and \fBfull\fR to include complete references (default: full).
.IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fInumber\fR (default: 76)" 4
.IX Item "--wrap-po no|newlines|number (default: 76)"
Specify how the po file should be wrapped. This gives the choice between either
files that are nicely wrapped but could lead to git conflicts, or files that are
easier to handle automatically, but harder to read for humans.
.Sp
Historically, the gettext suite has reformatted the po files at the 77th column
for cosmetics. This option specifies the behavior of po4a. If set to a numerical
value, po4a will wrap the po file after this column and after newlines in the
content. If set to \fBnewlines\fR, po4a will only split the msgid and msgstr after
newlines in the content. If set to \fBno\fR, po4a will not wrap the po file at all.
The reference comments are always wrapped by the gettext tools that we use internally.
.Sp
Note that this option has no impact on how the msgid and msgstr are wrapped, ie
on how newlines are added to the content of these strings.
.IP "\fB\-\-msgid\-bugs\-address\fR \fIemail@address\fR" 4
.IX Item "--msgid-bugs-address email@address"
Set the report address for msgid bugs. By default, the created \s-1POT\s0 files
have no Report-Msgid-Bugs-To fields.
.IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4
.IX Item "--copyright-holder string"
Set the copyright holder in the \s-1POT\s0 header. The default value is
\&\*(L"Free Software Foundation, Inc.\*(R"
.IP "\fB\-\-package\-name\fR \fIstring\fR" 4
.IX Item "--package-name string"
Set the package name for the \s-1POT\s0 header. The default is \*(L"\s-1PACKAGE\*(R".\s0
.IP "\fB\-\-package\-version\fR \fIstring\fR" 4
.IX Item "--package-version string"
Set the package version for the \s-1POT\s0 header. The default is \*(L"\s-1VERSION\*(R".\s0
.SH "Functions concerning entire message catalogs"
.IX Header "Functions concerning entire message catalogs"
.IP "\fBnew()\fR" 4
.IX Item "new()"
Creates a new message catalog. If an argument is provided, it's the name of
a \s-1PO\s0 file we should load.
.IP "read($)" 4
.IX Item "read($)"
Reads a \s-1PO\s0 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.
.IP "write($)" 4
.IX Item "write($)"
Writes the current catalog to the given file.
.IP "write_if_needed($$)" 4
.IX Item "write_if_needed($$)"
Like write, but if the \s-1PO\s0 or \s-1POT\s0 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 \s-1POT\s0 just to
update a line reference or the POT-Creation-Date field).
.IP "filter($)" 4
.IX Item "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.
.Sp
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.
.Sp
I love Perl sometimes ;)
.IP "\fBto_utf8()\fR" 4
.IX Item "to_utf8()"
Recodes to \s-1UTF\-8\s0 the \s-1PO\s0's msgstrs. Does nothing if the charset is not
specified in the \s-1PO\s0 file (\*(L"\s-1CHARSET\*(R"\s0 value), or if it's already \s-1UTF\-8\s0 or
\&\s-1ASCII.\s0
.SH "Functions to use a message catalog for translations"
.IX Header "Functions to use a message catalog for translations"
.IP "gettext($%)" 4
.IX Item "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.
.Sp
After the string to translate, you can pass a hash of extra
arguments. Here are the valid entries:
.RS 4
.IP "\fBwrap\fR" 4
.IX Item "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.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
the column at which we should wrap (default: 76).
.RE
.RS 4
.RE
.IP "\fBstats_get()\fR" 4
.IX Item "stats_get()"
Returns statistics about the hit ratio of gettext since the last time that
\&\fBstats_clear()\fR 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 \s-1PO\s0 file, while msgfmt reports the status of the
file.  Example of use:
.Sp
.Vb 1
\&    [some use of the PO file to translate stuff]
\&
\&    ($percent,$hit,$queries) = $pofile\->stats_get();
\&    print "So far, we found translations for $percent\e%  ($hit of $queries) of strings.\en";
.Ve
.IP "\fBstats_clear()\fR" 4
.IX Item "stats_clear()"
Clears the statistics about gettext hits.
.SH "Functions to build a message catalog"
.IX Header "Functions to build a message catalog"
.IP "push(%)" 4
.IX Item "push(%)"
Push a new entry at the end of the current catalog. The arguments should
form a hash table. The valid keys are:
.RS 4
.IP "\fBmsgid\fR" 4
.IX Item "msgid"
the string in original language.
.IP "\fBmsgstr\fR" 4
.IX Item "msgstr"
the translation.
.IP "\fBreference\fR" 4
.IX Item "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.
.IP "\fBcomment\fR" 4
.IX Item "comment"
a comment added here manually (by the translators). The format here is free.
.IP "\fBautomatic\fR" 4
.IX Item "automatic"
a comment which was automatically added by the string extraction
program. See the \fB\-\-add\-comments\fR option of the \fBxgettext\fR program for
more information.
.IP "\fBflags\fR" 4
.IX Item "flags"
space-separated list of all defined flags for this entry.
.Sp
Valid flags are: \fBc\-text\fR, \fBpython-text\fR, \fBlisp-text\fR, \fBelisp-text\fR, \fBlibrep-text\fR,
\&\fBsmalltalk-text\fR, \fBjava-text\fR, \fBawk-text\fR, \fBobject-pascal-text\fR, \fBycp-text\fR,
\&\fBtcl-text\fR, \fBwrap\fR, \fBno-wrap\fR and \fBfuzzy\fR.
.Sp
See the gettext documentation for their meaning.
.IP "\fBtype\fR" 4
.IX Item "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 \s-1PO\s0 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 \s-1PO\s0
objects are given a type, based on their structure (like \*(L"chapt\*(R", \*(L"sect1\*(R",
\&\*(L"p\*(R" 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.
.Sp
This information is written as automatic comment in the \s-1PO\s0 file since this
gives to translators some context about the strings to translate.
.IP "\fBwrap\fR" 4
.IX Item "wrap"
boolean indicating whether whitespaces can be mangled in cosmetic
reformattings. If true, the string is canonized before use.
.Sp
This information is written to the \s-1PO\s0 file using the \fBwrap\fR or \fBno-wrap\fR flag.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
the column at which we should wrap (default: 76).
.Sp
This information is not written to the \s-1PO\s0 file.
.RE
.RS 4
.RE
.SH "Miscellaneous functions"
.IX Header "Miscellaneous functions"
.IP "\fBcount_entries()\fR" 4
.IX Item "count_entries()"
Returns the number of entries in the catalog (without the header).
.IP "\fBcount_entries_doc()\fR" 4
.IX Item "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.
.IP "msgid($)" 4
.IX Item "msgid($)"
Returns the msgid of the given number.
.IP "msgid_doc($)" 4
.IX Item "msgid_doc($)"
Returns the msgid with the given position in the document.
.IP "type_doc($)" 4
.IX Item "type_doc($)"
Returns the type of the msgid with the given position in the document. This is
probably only useful to gettextization, and it's stored separately from
{$msgid}{'type'} because the later location may be overwritten by another type
when the \f(CW$msgid\fR is duplicated in the master document.
.IP "\fBget_charset()\fR" 4
.IX Item "get_charset()"
Returns the character set specified in the \s-1PO\s0 header. If it hasn't been
set, it will return \*(L"\s-1UTF\-8\*(R".\s0
.IP "set_charset($)" 4
.IX Item "set_charset($)"
This sets the character set of the \s-1PO\s0 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 \*(L"\s-1UTF\-8\*(R".\s0 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 \fBget_charset()\fR.
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve