1Locale::Maketext::ExtraUcste(r3)Contributed Perl DocumenLtoactailoen::Maketext::Extract(3)
2
6 Locale::Maketext::Extract - Extract translatable strings from source
7
9 version 1.00
10
12 my $Ext = Locale::Maketext::Extract->new;
13 $Ext->read_po('messages.po');
14 $Ext->extract_file($_) for <*.pl>;
15 # Set $entries_are_in_gettext_format if the .pl files above use
17 # loc('%1') instead of loc('[_1]')
18 $Ext->compile($entries_are_in_gettext_format);
19 $Ext->write_po('messages.po');
21 -----------------------------------
23 ### Specifying parser plugins ###
25 my $Ext = Locale::Maketext::Extract->new(
27 # Specify which parser plugins to use
29 plugins => {
30 # Use Perl parser, process files with extension .pl .pm .cgi
32 perl => [],
33 # Use YAML parser, process all files
35 yaml => ['*'],
36 # Use TT2 parser, process files with extension .tt2 .tt .html
38 # or which match the regex
39 tt2 => [
40 'tt2',
41 'tt',
42 'html',
43 qr/\.tt2?\./
44 ],
45 # Use My::Module as a parser for all files
47 'My::Module' => ['*'],
48 },
50 # Warn if a parser can't process a file or problems loading a plugin
52 warnings => 1,
53 # List processed files
55 verbose => 1,
56 );
58
60 This module can extract translatable strings from files, and write them
61 back to PO files. It can also parse existing PO files and merge their
62 contents with newly extracted strings.
63 A command-line utility, xgettext.pl, is installed with this module as
65 well.
66 The format parsers are loaded as plugins, so it is possible to define
68 your own parsers.
69 Following formats of input files are supported:
71 Perl source files (plugin: perl)
73 Valid localization function names are: "translate", "maketext",
74 "gettext", "l", "loc", "x", "_" and "__".
75 For a slightly more accurate, but much slower Perl parser, you can
77 use the PPI plugin. This does not have a short name (like "perl"),
78 but must be specified in full.
79 HTML::Mason (Mason 1) and Mason (Mason 2) (plugin: mason)
81 HTML::Mason (aka Mason 1)
82 Strings inside <&|/l>...</&> and <&|/loc>...</&> are extracted.
83 Mason (aka Mason 2) Strings inside <% $.floc { %>...</%> or <% $.fl
85 { %>...</%> or <% $self->floc { %>...</%> or <% $self->fl {
86 %>...</%> are extracted.
87 Template Toolkit (plugin: tt2)
89 Valid forms are:
90 [% | l(arg1,argn) %]string[% END %]
92 [% 'string' | l(arg1,argn) %]
93 [% l('string',arg1,argn) %]
94 FILTER and | are interchangeable
96 l and loc are interchangeable
97 args are optional
98 Text::Template (plugin: text)
100 Sentences between "STARTxxx" and "ENDxxx" are extracted
101 individually.
102 YAML (plugin: yaml)
104 Valid forms are _"string" or _'string', eg:
105 title: _"My title"
107 desc: _'My "quoted" string'
108 Quotes do not have to be escaped, so you could also do:
110 desc: _"My "quoted" string"
112 HTML::FormFu (plugin: formfu)
114 HTML::FormFu uses a config-file to generate forms, with built in
115 support for localizing errors, labels etc.
116 We extract the text after "_loc: ":
118 content_loc: this is the string
119 message_loc: ['Max string length: [_1]', 10]
120 Generic Template (plugin: generic)
122 Strings inside {{...}} are extracted.
123
125 Constructor
126 new()
127 new(
129 plugins => {...},
130 warnings => 1 | 0,
131 verbose => 0 | 1 | 2 | 3,
132 )
133 See "Plugins", "Warnings" and "Verbose" for details
135 Plugins
137 $ext->plugins({...});
138 Locale::Maketext::Extract uses plugins (see below for the list) to
140 parse different formats.
141 Each plugin can also specify which file types it can parse.
143 # use only the YAML plugin
145 # only parse files with the default extension list defined in the plugin
146 # ie .yaml .yml .conf
147 $ext->plugins({
149 yaml => [],
150 })
151 # use only the Perl plugin
154 # parse all file types
155 $ext->plugins({
157 perl => '*'
158 })
159 $ext->plugins({
161 tt2 => [
162 'tt', # matches base filename against /\.tt$/
163 qr/\.tt2?\./, # matches base filename against regex
164 \&my_filter, # codref called
165 ]
166 })
167 sub my_filter {
169 my ($base_filename,$path_to_file) = @_;
170 return 1 | 0;
172 }
173 # Specify your own parser
175 # only parse files with the default extension list defined in the plugin
176 $ext->plugins({
178 'My::Extract::Parser' => []
179 })
180 By default, if no plugins are specified, it first tries to determine
182 which plugins are intended specifically for the file type and uses
183 them. If no such plugins are found, it then uses all of the builtin
184 plugins, overriding the file types specified in each.
185 Available plugins
187 "perl" : Locale::Maketext::Extract::Plugin::Perl
189 For a slightly more accurate but much slower Perl parser, you can
190 use the PPI plugin. This does not have a short name, but must be
191 specified in full, ie: Locale::Maketext::Extract::Plugin::PPI
192 "tt2" : Locale::Maketext::Extract::Plugin::TT2
194 "yaml" : Locale::Maketext::Extract::Plugin::YAML
195 "formfu" : Locale::Maketext::Extract::Plugin::FormFu
196 "mason" : Locale::Maketext::Extract::Plugin::Mason
197 "text" : Locale::Maketext::Extract::Plugin::TextTemplate
198 "generic" : Locale::Maketext::Extract::Plugin::Generic
199 Also, see Locale::Maketext::Extract::Plugin::Base for details of how to
201 write your own plugin.
202 Warnings
204 Because the YAML and TT2 plugins use proper parsers, rather than just
205 regexes, if a source file is not valid and it is unable to parse the
206 file, then the parser will throw an error and abort parsing.
207 The next enabled plugin will be tried.
209 By default, you will not see these errors. If you would like to see
211 them, then enable warnings via new(). All parse errors will be printed
212 to STDERR.
213 Also, if developing your own plugin, turn on warnings to see any errors
215 that result from loading your plugin.
216 Verbose
218 If you would like to see which files have been processed, which plugins
219 were used, and which strings were extracted, then enable "verbose". If
220 no acceptable plugin was found, or no strings were extracted, then the
221 file is not listed:
222 $ext = Locale::Extract->new( verbose => 1 | 2 | 3);
224 OR
226 xgettext.pl ... -v # files reported
227 xgettext.pl ... -v -v # files and plugins reported
228 xgettext.pl ... -v -v -v # files, plugins and strings reported
229 Accessors
231 header, set_header
232 lexicon, set_lexicon, msgstr, set_msgstr
233 entries, set_entries, entry, add_entry, del_entry
234 compiled_entries, set_compiled_entries, compiled_entry,
235 add_compiled_entry, del_compiled_entry
236 clear
237 PO File manipulation
239 method read_po ($file)
240 method write_po ($file, $add_format_marker?)
242 Extraction
244 extract
245 extract_file
246 Compilation
248 compile($entries_are_in_gettext_style?)
249 Merges the "entries" into "compiled_entries".
251 If $entries_are_in_gettext_style is true, the previously extracted
253 entries are assumed to be in the Gettext style (e.g. %1).
254 Otherwise they are assumed to be in Maketext style (e.g. "[_1]") and
256 are converted into Gettext style before merging into
257 "compiled_entries".
258 The "entries" are not cleared after each compilation; use
260 "-"set_entries()> to clear them if you need to extract from sources
261 with varying styles.
262 normalize_space
264 Lexicon accessors
266 msgids, has_msgid,
267 msgstr, set_msgstr
268 msg_positions, msg_variables, msg_format, msg_out
269 Internal utilities
271 _default_header
272 _maketext_to_gettext
273 _escape
274 _format
275 _plugins_specifically_for_file
276
278 Thanks to Jesse Vincent for contributing to an early version of this
279 module.
280 Also to Alain Barbet, who effectively re-wrote the source parser with a
282 flex-like algorithm.
283
285 xgettext.pl, Locale::Maketext, Locale::Maketext::Lexicon
286
288 Audrey Tang <cpan@audreyt.org>
289
291 Copyright 2003-2013 by Audrey Tang <cpan@audreyt.org>.
292 This software is released under the MIT license cited below.
294 The "MIT" License
296 Permission is hereby granted, free of charge, to any person obtaining a
297 copy of this software and associated documentation files (the
298 "Software"), to deal in the Software without restriction, including
299 without limitation the rights to use, copy, modify, merge, publish,
300 distribute, sublicense, and/or sell copies of the Software, and to
301 permit persons to whom the Software is furnished to do so, subject to
302 the following conditions:
303 The above copyright notice and this permission notice shall be included
305 in all copies or substantial portions of the Software.
306 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
308 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
309 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
310 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
311 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
312 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
313 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
314
316 • Clinton Gormley <drtech@cpan.org>
317 • Audrey Tang <cpan@audreyt.org>
319
321 This software is Copyright (c) 2014 by Audrey Tang.
322 This is free software, licensed under:
324 The MIT (X11) License
326perl v5.36.0 2023-01-20 Locale::Maketext::Extract(3)