1PO(3) User Contributed Perl Documentation 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>);
25 $href = Locale::PO->load_file_ashash(<filename>);
26 Locale::PO->save_file_fromarray(<filename>,$aref);
27 Locale::PO->save_file_fromhash(<filename>,$href);
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, msgstr, msgctxt, comment, automatic,
46 reference, fuzzy, and c-format. See accessor methods below.
47 To generate a po file header, add an entry with an empty msgid,
49 like this:
50 $po = new Locale::PO(-msgid=>'', -msgstr=>
52 "Project-Id-Version: PACKAGE VERSION\\n" .
53 "PO-Revision-Date: YEAR-MO-DA HO:MI +ZONE\\n" .
54 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\\n" .
55 "Language-Team: LANGUAGE <LL@li.org>\\n" .
56 "MIME-Version: 1.0\\n" .
57 "Content-Type: text/plain; charset=CHARSET\\n" .
58 "Content-Transfer-Encoding: ENCODING\\n");
59 msgid
61 Set or get the untranslated string from the object.
62 This method expects the new string in unquoted form but returns the
64 current string in quoted form.
65 msgid_plural
67 Set or get the untranslated plural string from the object.
68 This method expects the new string in unquoted form but returns the
70 current string in quoted form.
71 msgstr
73 Set or get the translated string from the object.
74 This method expects the new string in unquoted form but returns the
76 current string in quoted form.
77 msgstr_n
79 Get or set the translations if there are purals involved. Takes and
80 returns a hashref where the keys are the 'N' case and the values
81 are the strings. eg:
82 $po->msgstr_n(
84 {
85 0 => 'found %d plural translations',
86 1 => 'found %d singular translation',
87 }
88 );
89 This method expects the new strings in unquoted form but returns
91 the current strings in quoted form.
92 msgctxt
94 Set or get the translation context string from the object.
95 This method expects the new string in unquoted form but returns the
97 current string in quoted form.
98 obsolete
100 Returns 1 if the entry is obsolete. Obsolete entries have their
101 msgid, msgid_plural, msgstr, msgstr_n and msgctxt lines commented
102 out with "#~"
103 When using load_file_ashash, non-obsolete entries will always
105 replace obsolete entries with the same msgid.
106 comment
108 Set or get translator comments from the object.
109 If there are no such comments, then the value is undef. Otherwise,
111 the value is a string that contains the comment lines delimited
112 with "\n". The string includes neither the "# " at the beginning
113 of each comment line nor the newline at the end of the last comment
114 line.
115 automatic
117 Set or get automatic comments from the object (inserted by emacs
118 po-mode or xgettext).
119 If there are no such comments, then the value is undef. Otherwise,
121 the value is a string that contains the comment lines delimited
122 with "\n". The string includes neither the "#. " at the beginning
123 of each comment line nor the newline at the end of the last comment
124 line.
125 reference
127 Set or get reference marking comments from the object (inserted by
128 emacs po-mode or gettext).
129 fuzzy
131 Set or get the fuzzy flag on the object ("check this translation").
132 When setting, use 1 to turn on fuzzy, and 0 to turn it off.
133 c_format
135 Set or get the c-format or no-c-format flag on the object.
136 This can take 3 values: 1 implies c-format, 0 implies no-c-format,
138 and undefined implies neither.
139 php_format
141 Set or get the php-format or no-php-format flag on the object.
142 This can take 3 values: 1 implies php-format, 0 implies no-php-
144 format, and undefined implies neither.
145 has_flag
147 if ($po->has_flag('perl-format')) {
148 ...
149 }
150 Returns true if the flag exists in the entry's #~ comment
152 add_flag
154 $po->add_flag('perl-format');
155 Adds the flag to the #~ comment
157 remove_flag
159 $po->remove_flag('perl-format');
160 Removes the flag from the #~ comment
162 loaded_line_number
164 When using one of the load_file_as* methods, this will return the
165 line number that the entry started at in the file.
166 dump
168 Returns the entry as a string, suitable for output to a po file.
169 quote
171 Applies po quotation rules to a string, and returns the quoted
172 string. The quoted string will have all existing double-quote
173 characters escaped by backslashes, and will be enclosed in double
174 quotes.
175 dequote
177 Returns a quoted po string to its natural form.
178 load_file_asarray
180 Given the filename of a po-file, reads the file and returns a
181 reference to a list of Locale::PO objects corresponding to the
182 contents of the file, in the same order.
183 load_file_ashash
185 Given the filename of a po-file, reads the file and returns a
186 reference to a hash of Locale::PO objects corresponding to the
187 contents of the file. The hash keys are the untranslated strings,
188 so this is a cheap way to remove duplicates. The method will prefer
189 to keep entries that have been translated.
190 save_file_fromarray
192 Given a filename and a reference to a list of Locale::PO objects,
193 saves those objects to the file, creating a po-file.
194 save_file_fromhash
196 Given a filename and a reference to a hash of Locale::PO objects,
197 saves those objects to the file, creating a po-file. The entries
198 are sorted alphabetically by untranslated string.
199
201 Maintainer: Ken Prows, perl@xev.net
202 Original version by: Alan Schwartz, alansz@pennmush.org
204
206 If you load_file_as* then save_file_from*, the output file may have
207 slight cosmetic differences from the input file (an extra blank line
208 here or there).
209 msgid, msgid_plural, msgstr, msgstr_n and msgctxt expect a non-quoted
211 string as input, but return quoted strings. I'm hesitant to change
212 this in fear of breaking the modules/scripts of people already using
213 Locale::PO.
214 Locale::PO requires blank lines between entries, but Uniforum style PO
216 files don't have any.
217 Please submit all bug requests using CPAN's ticketing system.
219
221 xgettext(1).
222perl v5.10.1 2008-05-19 PO(3)