1PO(3)                 User Contributed Perl Documentation                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>);
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

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, msgstr, msgctxt, comment, automatic,
46           reference, fuzzy, and c-format. See accessor methods below.
47
48           To generate a po file header, add an entry with an empty msgid,
49           like this:
50
51                   $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
60       msgid
61           Set or get the untranslated string from the object.
62
63           This method expects the new string in unquoted form but returns the
64           current string in quoted form.
65
66       msgid_plural
67           Set or get the untranslated plural string from the object.
68
69           This method expects the new string in unquoted form but returns the
70           current string in quoted form.
71
72       msgstr
73           Set or get the translated string from the object.
74
75           This method expects the new string in unquoted form but returns the
76           current string in quoted form.
77
78       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
83                   $po->msgstr_n(
84                       {
85                           0 => 'found %d plural translations',
86                           1 => 'found %d singular translation',
87                       }
88                   );
89
90           This method expects the new strings in unquoted form but returns
91           the current strings in quoted form.
92
93       msgctxt
94           Set or get the translation context string from the object.
95
96           This method expects the new string in unquoted form but returns the
97           current string in quoted form.
98
99       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
104           When using load_file_ashash, non-obsolete entries will always
105           replace obsolete entries with the same msgid.
106
107       comment
108           Set or get translator comments from the object.
109
110           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
116       automatic
117           Set or get automatic comments from the object (inserted by emacs
118           po-mode or xgettext).
119
120           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
126       reference
127           Set or get reference marking comments from the object (inserted by
128           emacs po-mode or gettext).
129
130       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
134       c_format
135           Set or get the c-format or no-c-format flag on the object.
136
137           This can take 3 values: 1 implies c-format, 0 implies no-c-format,
138           and undefined implies neither.
139
140       php_format
141           Set or get the php-format or no-php-format flag on the object.
142
143           This can take 3 values: 1 implies php-format, 0 implies no-php-
144           format, and undefined implies neither.
145
146       has_flag
147                   if ($po->has_flag('perl-format')) {
148                           ...
149                   }
150
151           Returns true if the flag exists in the entry's #~ comment
152
153       add_flag
154                   $po->add_flag('perl-format');
155
156           Adds the flag to the #~ comment
157
158       remove_flag
159                   $po->remove_flag('perl-format');
160
161           Removes the flag from the #~ comment
162
163       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
167       dump
168           Returns the entry as a string, suitable for output to a po file.
169
170       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
176       dequote
177           Returns a quoted po string to its natural form.
178
179       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
184       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
191       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
195       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

AUTHOR

201       Maintainer: Ken Prows, perl@xev.net
202
203       Original version by: Alan Schwartz, alansz@pennmush.org
204

BUGS

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
210       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
215       Locale::PO requires blank lines between entries, but Uniforum style PO
216       files don't have any.
217
218       Please submit all bug requests using CPAN's ticketing system.
219

SEE ALSO

221       xgettext(1).
222
223
224
225perl v5.12.0                      2008-05-19                             PO(3)
Impressum