1Locale::Maketext::ExtraUcste(r3)Contributed Perl DocumenLtoactailoen::Maketext::Extract(3)
2
6 Locale::Maketext::Extract - Extract translatable strings from source
7
9 my $Ext = Locale::Maketext::Extract->new;
10 $Ext->read_po('messages.po');
11 $Ext->extract_file($_) for <*.pl>;
12 # Set $entries_are_in_gettext_format if the .pl files above use
14 # loc('%1') instead of loc('[_1]')
15 $Ext->compile($entries_are_in_gettext_format);
16 $Ext->write_po('messages.po');
18 -----------------------------------
20 ### Specifying parser plugins ###
22 my $Ext = Locale::Maketext::Extract->new(
24 # Specify which parser plugins to use
26 plugins => {
27 # Use Perl parser, process files with extension .pl .pm .cgi
29 perl => [],
30 # Use YAML parser, process all files
32 yaml => ['*'],
33 # Use TT2 parser, process files with extension .tt2 .tt .html
35 # or which match the regex
36 tt2 => [
37 'tt2',
38 'tt',
39 'html',
40 qr/\.tt2?\./
41 ],
42 # Use My::Module as a parser for all files
44 'My::Module' => ['*'],
45 },
47 # Warn if a parser can't process a file
49 warnings => 1,
50 # List processed files
52 verbose => 1,
53 );
55
57 This module can extract translatable strings from files, and write them
58 back to PO files. It can also parse existing PO files and merge their
59 contents with newly extracted strings.
60 A command-line utility, xgettext.pl, is installed with this module as
62 well.
63 The format parsers are loaded as plugins, so it is possible to define
65 your own parsers.
66 Following formats of input files are supported:
68 Perl source files (plugin: perl)
70 Valid localization function names are: "translate", "maketext",
71 "gettext", "loc", "x", "_" and "__".
72 For a slightly more accurate, but much slower Perl parser, you can
74 use the PPI plugin. This does not have a short name (like "perl"),
75 but must be specified in full.
76 HTML::Mason (plugin: mason)
78 Strings inside "<&|/l>...</&>" and "<&|/loc>...</&>" are extracted.
79 Template Toolkit (plugin: tt2)
81 Valid forms are:
82 [% | l(arg1,argn) %]string[% END %]
84 [% 'string' | l(arg1,argn) %]
85 [% l('string',arg1,argn) %]
86 FILTER and | are interchangeable
88 l and loc are interchangeable
89 args are optional
90 Text::Template (plugin: text)
92 Sentences between "STARTxxx" and "ENDxxx" are extracted
93 individually.
94 YAML (plugin: yaml)
96 Valid forms are _"string" or _'string', eg:
97 title: _"My title"
99 desc: _'My "quoted" string'
100 Quotes do not have to be escaped, so you could also do:
102 desc: _"My "quoted" string"
104 HTML::FormFu (plugin: formfu)
106 HTML::FormFu uses a config-file to generate forms, with built in
107 support for localizing errors, labels etc.
108 We extract the text after "_loc: ":
110 content_loc: this is the string
111 message_loc: ['Max string length: [_1]', 10]
112 Generic Template (plugin: generic)
114 Strings inside {{...}} are extracted.
115
117 Constructor
118 new()
119 new(
121 plugins => {...},
122 warnings => 1 | 0,
123 verbose => 0 | 1 | 2 | 3,
124 )
125 See "Plugins", "Warnings" and "Verbose" for details
127 Plugins
129 $ext->plugins({...});
130 Locale::Maketext::Extract uses plugins (see below for the list) to
132 parse different formats.
133 Each plugin can also specify which file types it can parse.
135 # use only the YAML plugin
137 # only parse files with the default extension list defined in the plugin
138 # ie .yaml .yml .conf
139 $ext->plugins({
141 yaml => [],
142 })
143 # use only the Perl plugin
146 # parse all file types
147 $ext->plugins({
149 perl => '*'
150 })
151 $ext->plugins({
153 tt2 => [
154 'tt', # matches base filename against /\.tt$/
155 qr/\.tt2?\./, # matches base filename against regex
156 \&my_filter, # codref called
157 ]
158 })
159 sub my_filter {
161 my ($base_filename,$path_to_file) = @_;
162 return 1 | 0;
164 }
165 # Specify your own parser
167 # only parse files with the default extension list defined in the plugin
168 $ext->plugins({
170 'My::Extract::Parser' => []
171 })
172 By default, if no plugins are specified, then it uses all of the
174 builtin plugins, and overrides the file types specified in each plugin
175 - instead, each plugin is tried for every file.
176 Available plugins
178 "perl" : Locale::Maketext::Extract::Plugin::Perl
180 For a slightly more accurate but much slower Perl parser, you can
181 use the PPI plugin. This does not have a short name, but must be
182 specified in full, ie: Locale::Maketext::Extract::Plugin::PPI
183 "tt2" : Locale::Maketext::Extract::Plugin::TT2
185 "yaml" : Locale::Maketext::Extract::Plugin::YAML
186 "formfu" : Locale::Maketext::Extract::Plugin::FormFu
187 "mason" : Locale::Maketext::Extract::Plugin::Mason
188 "text" : Locale::Maketext::Extract::Plugin::TextTemplate
189 "generic" : Locale::Maketext::Extract::Plugin::Generic
190 Also, see Locale::Maketext::Extract::Plugin::Base for details of how to
192 write your own plugin.
193 Warnings
195 Because the YAML and TT2 plugins use proper parsers, rather than just
196 regexes, if a source file is not valid and it is unable to parse the
197 file, then the parser will throw an error and abort parsing.
198 The next enabled plugin will be tried.
200 By default, you will not see these errors. If you would like to see
202 them, then enable warnings via new(). All parse errors will be printed
203 to STDERR.
204 Verbose
206 If you would like to see which files have been processed, which plugins
207 were used, and which strings were extracted, then enable "verbose". If
208 no acceptable plugin was found, or no strings were extracted, then the
209 file is not listed:
210 $ext = Locale::Extract->new( verbose => 1 | 2 | 3);
212 OR
214 xgettext.pl ... -v # files reported
215 xgettext.pl ... -v -v # files and plugins reported
216 xgettext.pl ... -v -v -v # files, plugins and strings reported
217 Accessors
219 header, set_header
220 lexicon, set_lexicon, msgstr, set_msgstr
221 entries, set_entries, entry, add_entry, del_entry
222 compiled_entries, set_compiled_entries, compiled_entry,
223 add_compiled_entry, del_compiled_entry
224 clear
225 PO File manipulation
227 method read_po ($file)
228 method write_po ($file, $add_format_marker?)
230 Extraction
232 extract
233 extract_file
234 Compilation
236 compile($entries_are_in_gettext_style?)
237 Merges the "entries" into "compiled_entries".
239 If $entries_are_in_gettext_style is true, the previously extracted
241 entries are assumed to be in the Gettext style (e.g. %1).
242 Otherwise they are assumed to be in Maketext style (e.g. "[_1]") and
244 are converted into Gettext style before merging into
245 "compiled_entries".
246 The "entries" are not cleared after each compilation; use
248 "-"set_entries()> to clear them if you need to extract from sources
249 with varying styles.
250 normalize_space
252 Lexicon accessors
254 msgids, has_msgid,
255 msgstr, set_msgstr
256 msg_positions, msg_variables, msg_format, msg_out
257 Internal utilities
259 _default_header
260 _maketext_to_gettext
261 _escape
262 _format
263
265 Thanks to Jesse Vincent for contributing to an early version of this
266 module.
267 Also to Alain Barbet, who effectively re-wrote the source parser with a
269 flex-like algorithm.
270
272 xgettext.pl, Locale::Maketext, Locale::Maketext::Lexicon
273
275 Audrey Tang <cpan@audreyt.org>
276
278 Copyright 2003-2008 by Audrey Tang <cpan@audreyt.org>.
279 This software is released under the MIT license cited below.
281 The "MIT" License
283 Permission is hereby granted, free of charge, to any person obtaining a
284 copy of this software and associated documentation files (the
285 "Software"), to deal in the Software without restriction, including
286 without limitation the rights to use, copy, modify, merge, publish,
287 distribute, sublicense, and/or sell copies of the Software, and to
288 permit persons to whom the Software is furnished to do so, subject to
289 the following conditions:
290 The above copyright notice and this permission notice shall be included
292 in all copies or substantial portions of the Software.
293 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
295 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
296 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
297 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
298 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
299 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
300 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
301perl v5.12.2 2010-12-24 Locale::Maketext::Extract(3)