1Locale::PO(3)         User Contributed Perl Documentation        Locale::PO(3)
2
3
4

NAME

6       Locale::PO - Perl module for manipulating .po entries from GNU gettext
7

SYNOPSIS

9           use Locale::PO;
10
11           $po = new Locale::PO([-option=>value,...])
12           [$string =] $po->msgid([new string]);
13           [$string =] $po->msgstr([new string]);
14           [$string =] $po->comment([new string]);
15           [$string =] $po->automatic([new string]);
16           [$string =] $po->reference([new string]);
17           [$value =] $po->fuzzy([value]);
18           [$value =] $po->add_flag('c-format');
19           print $po->dump;
20
21           $quoted_string = $po->quote($string);
22           $string = $po->dequote($quoted_string);
23
24           $aref = Locale::PO->load_file_asarray(<filename>,[encoding]);
25           $href = Locale::PO->load_file_ashash(<filename>,[encoding]);
26           Locale::PO->save_file_fromarray(<filename>,$aref,[encoding]);
27           Locale::PO->save_file_fromhash(<filename>,$href,[encoding]);
28

DESCRIPTION

30       This module simplifies management of GNU gettext .po files and is an
31       alternative to using emacs po-mode. It provides an object-oriented
32       interface in which each entry in a .po file is a Locale::PO object.
33

METHODS

35       new
36               my Locale::PO $po = new Locale::PO;
37               my Locale::PO $po = new Locale::PO(%options);
38
39           Create a new Locale::PO object to represent a po entry.  You can
40           optionally set the attributes of the entry by passing a list/hash
41           of the form:
42
43               -option=>value, -option=>value, etc.
44
45           Where options are msgid, msgid_plural, msgstr, msgctxt, comment,
46           automatic, reference, fuzzy_msgctxt, fuzzy_msgid,
47           fuzzy_msgid_plural, fuzzy, and c-format. See accessor methods
48           below.
49
50           To generate a po file header, add an entry with an empty msgid,
51           like this:
52
53               $po = new Locale::PO(-msgid=>'', -msgstr=>
54                       "Project-Id-Version: PACKAGE VERSION\\n" .
55                       "PO-Revision-Date: YEAR-MO-DA HO:MI +ZONE\\n" .
56                       "Last-Translator: FULL NAME <EMAIL@ADDRESS>\\n" .
57                       "Language-Team: LANGUAGE <LL@li.org>\\n" .
58                       "MIME-Version: 1.0\\n" .
59                       "Content-Type: text/plain; charset=CHARSET\\n" .
60                       "Content-Transfer-Encoding: ENCODING\\n");
61
62       msgid
63           Set or get the untranslated string from the object.
64
65           This method expects the new string in unquoted form but returns the
66           current string in quoted form.
67
68       msgid_plural
69           Set or get the untranslated plural string from the object.
70
71           This method expects the new string in unquoted form but returns the
72           current string in quoted form.
73
74       msgstr
75           Set or get the translated string from the object.
76
77           This method expects the new string in unquoted form but returns the
78           current string in quoted form.
79
80       msgstr_n
81           Get or set the translations if there are purals involved. Takes and
82           returns a hashref where the keys are the 'N' case and the values
83           are the strings. eg:
84
85               $po->msgstr_n(
86                   {
87                       0 => 'found %d plural translations',
88                       1 => 'found %d singular translation',
89                   }
90               );
91
92           This method expects the new strings in unquoted form but returns
93           the current strings in quoted form.
94
95       msgctxt
96           Set or get the translation context string from the object.
97
98           This method expects the new string in unquoted form but returns the
99           current string in quoted form.
100
101       fuzzy_msgid
102           Set or get the outdated untranslated string from the object.
103
104           This method expects the new string in unquoted form but returns the
105           current string in quoted form.
106
107       fuzzy_msgid_plural
108           Set or get the outdated untranslated plural string from the object.
109
110           This method expects the new string in unquoted form but returns the
111           current string in quoted form.
112
113       fuzzy_msgctxt
114           Set or get the outdated translation context string from the object.
115
116           This method expects the new string in unquoted form but returns the
117           current string in quoted form.
118
119       obsolete
120           Returns 1 if the entry is obsolete.  Obsolete entries have their
121           msgid, msgid_plural, msgstr, msgstr_n and msgctxt lines commented
122           out with "#~"
123
124           When using load_file_ashash, non-obsolete entries will always
125           replace obsolete entries with the same msgid.
126
127       comment
128           Set or get translator comments from the object.
129
130           If there are no such comments, then the value is undef.  Otherwise,
131           the value is a string that contains the comment lines delimited
132           with "\n".  The string includes neither the "# " at the beginning
133           of each comment line nor the newline at the end of the last comment
134           line.
135
136       automatic
137           Set or get automatic comments from the object (inserted by emacs
138           po-mode or xgettext).
139
140           If there are no such comments, then the value is undef.  Otherwise,
141           the value is a string that contains the comment lines delimited
142           with "\n".  The string includes neither the "#. " at the beginning
143           of each comment line nor the newline at the end of the last comment
144           line.
145
146       reference
147           Set or get reference marking comments from the object (inserted by
148           emacs po-mode or gettext).
149
150       fuzzy
151           Set or get the fuzzy flag on the object ("check this translation").
152           When setting, use 1 to turn on fuzzy, and 0 to turn it off.
153
154       c_format
155           Set or get the c-format or no-c-format flag on the object.
156
157           This can take 3 values: 1 implies c-format, 0 implies no-c-format,
158           and undefined implies neither.
159
160       php_format
161           Set or get the php-format or no-php-format flag on the object.
162
163           This can take 3 values: 1 implies php-format, 0 implies no-php-
164           format, and undefined implies neither.
165
166       has_flag
167               if ($po->has_flag('perl-format')) {
168                       ...
169               }
170
171           Returns true if the flag exists in the entry's #~ comment
172
173       add_flag
174               $po->add_flag('perl-format');
175
176           Adds the flag to the #~ comment
177
178       remove_flag
179               $po->remove_flag('perl-format');
180
181           Removes the flag from the #~ comment
182
183       loaded_line_number
184           When using one of the load_file_as* methods, this will return the
185           line number that the entry started at in the file.
186
187       dump
188           Returns the entry as a string, suitable for output to a po file.
189
190       quote
191           Applies po quotation rules to a string, and returns the quoted
192           string. The quoted string will have all existing double-quote
193           characters escaped by backslashes, and will be enclosed in double
194           quotes.
195
196       dequote
197           Returns a quoted po string to its natural form.
198
199       load_file_asarray
200           Given the filename of a po-file, reads the file and returns a
201           reference to a list of Locale::PO objects corresponding to the
202           contents of the file, in the same order.  Accepts an optional
203           encoding parameter (e.g.  "utf8") which defines how the po-file's
204           input stream will be configured.
205
206       load_file_ashash
207           Given the filename of a po-file, reads the file and returns a
208           reference to a hash of Locale::PO objects corresponding to the
209           contents of the file. The hash keys are the untranslated strings,
210           so this is a cheap way to remove duplicates. The method will prefer
211           to keep entries that have been translated.  Accepts an optional
212           encoding parameter (e.g.  "utf8") which defines how the po-file's
213           input stream will be configured.
214
215       save_file_fromarray
216           Given a filename and a reference to a list of Locale::PO objects,
217           saves those objects to the file, creating a po-file.  Accepts an
218           optional encoding parameter (e.g. "utf8") which defines how the po-
219           file's output stream will be configured.
220
221       save_file_fromhash
222           Given a filename and a reference to a hash of Locale::PO objects,
223           saves those objects to the file, creating a po-file. The entries
224           are sorted alphabetically by untranslated string.  Accepts an
225           optional encoding parameter (e.g. "utf8") which defines how the po-
226           file's output stream will be configured.
227

AUTHOR

229       Maintainer: Ken Prows, perl@xev.net
230
231       Original version by: Alan Schwartz, alansz@pennmush.org
232

BUGS

234       If you load_file_as* then save_file_from*, the output file may have
235       slight cosmetic differences from the input file (an extra blank line
236       here or there).
237
238       msgid, msgid_plural, msgstr, msgstr_n and msgctxt expect a non-quoted
239       string as input, but return quoted strings.  I'm hesitant to change
240       this in fear of breaking the modules/scripts of people already using
241       Locale::PO.
242
243       Locale::PO requires blank lines between entries, but Uniforum style PO
244       files don't have any.
245
246       Please submit all bug requests using CPAN's ticketing system.
247

SEE ALSO

249       xgettext(1).
250
251
252
253perl v5.34.0                      2022-01-21                     Locale::PO(3)
Impressum