1Locale::PO(3) User Contributed Perl Documentation Locale::PO(3)
2
6 Locale::PO - Perl module for manipulating .po entries from GNU gettext
7
9 use Locale::PO;
10 $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 $quoted_string = $po->quote($string);
22 $string = $po->dequote($quoted_string);
23 $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
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
35 new
36 my Locale::PO $po = new Locale::PO;
37 my Locale::PO $po = new Locale::PO(%options);
38 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 -option=>value, -option=>value, etc.
44 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 To generate a po file header, add an entry with an empty msgid,
51 like this:
52 $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 msgid
63 Set or get the untranslated string from the object.
64 This method expects the new string in unquoted form but returns the
66 current string in quoted form.
67 msgid_plural
69 Set or get the untranslated plural string from the object.
70 This method expects the new string in unquoted form but returns the
72 current string in quoted form.
73 msgstr
75 Set or get the translated string from the object.
76 This method expects the new string in unquoted form but returns the
78 current string in quoted form.
79 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 $po->msgstr_n(
86 {
87 0 => 'found %d plural translations',
88 1 => 'found %d singular translation',
89 }
90 );
91 This method expects the new strings in unquoted form but returns
93 the current strings in quoted form.
94 msgctxt
96 Set or get the translation context string from the object.
97 This method expects the new string in unquoted form but returns the
99 current string in quoted form.
100 fuzzy_msgid
102 Set or get the outdated untranslated string from the object.
103 This method expects the new string in unquoted form but returns the
105 current string in quoted form.
106 fuzzy_msgid_plural
108 Set or get the outdated untranslated plural string from the object.
109 This method expects the new string in unquoted form but returns the
111 current string in quoted form.
112 fuzzy_msgctxt
114 Set or get the outdated translation context string from the object.
115 This method expects the new string in unquoted form but returns the
117 current string in quoted form.
118 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 When using load_file_ashash, non-obsolete entries will always
125 replace obsolete entries with the same msgid.
126 comment
128 Set or get translator comments from the object.
129 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 automatic
137 Set or get automatic comments from the object (inserted by emacs
138 po-mode or xgettext).
139 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 reference
147 Set or get reference marking comments from the object (inserted by
148 emacs po-mode or gettext).
149 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 c_format
155 Set or get the c-format or no-c-format flag on the object.
156 This can take 3 values: 1 implies c-format, 0 implies no-c-format,
158 and undefined implies neither.
159 php_format
161 Set or get the php-format or no-php-format flag on the object.
162 This can take 3 values: 1 implies php-format, 0 implies no-php-
164 format, and undefined implies neither.
165 has_flag
167 if ($po->has_flag('perl-format')) {
168 ...
169 }
170 Returns true if the flag exists in the entry's #~ comment
172 add_flag
174 $po->add_flag('perl-format');
175 Adds the flag to the #~ comment
177 remove_flag
179 $po->remove_flag('perl-format');
180 Removes the flag from the #~ comment
182 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 dump
188 Returns the entry as a string, suitable for output to a po file.
189 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 dequote
197 Returns a quoted po string to its natural form.
198 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 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 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 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
229 Maintainer: Ken Prows, perl@xev.net
230 Original version by: Alan Schwartz, alansz@pennmush.org
232
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 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 Locale::PO requires blank lines between entries, but Uniforum style PO
244 files don't have any.
245 Please submit all bug requests using CPAN's ticketing system.
247
249 xgettext(1).
250perl v5.36.0 2022-07-22 Locale::PO(3)