1Locale::Maketext::ExtraUcste(r3)Contributed Perl DocumenLtoactailoen::Maketext::Extract(3)
2
3
4

NAME

6       Locale::Maketext::Extract - Extract translatable strings from source
7

VERSION

9       version 1.00
10

SYNOPSIS

12           my $Ext = Locale::Maketext::Extract->new;
13           $Ext->read_po('messages.po');
14           $Ext->extract_file($_) for <*.pl>;
15
16           # 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
20           $Ext->write_po('messages.po');
21
22           -----------------------------------
23
24           ### Specifying parser plugins ###
25
26           my $Ext = Locale::Maketext::Extract->new(
27
28               # Specify which parser plugins to use
29               plugins => {
30
31                   # Use Perl parser, process files with extension .pl .pm .cgi
32                   perl => [],
33
34                   # Use YAML parser, process all files
35                   yaml => ['*'],
36
37                   # 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
46                   # Use My::Module as a parser for all files
47                   'My::Module' => ['*'],
48
49               },
50
51               # Warn if a parser can't process a file or problems loading a plugin
52               warnings => 1,
53
54               # List processed files
55               verbose => 1,
56
57           );
58

DESCRIPTION

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
64       A command-line utility, xgettext.pl, is installed with this module as
65       well.
66
67       The format parsers are loaded as plugins, so it is possible to define
68       your own parsers.
69
70       Following formats of input files are supported:
71
72       Perl source files  (plugin: perl)
73           Valid localization function names are: "translate", "maketext",
74           "gettext", "l", "loc", "x", "_" and "__".
75
76           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
80       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
84           Mason (aka Mason 2) Strings inside <% $.floc { %>...</%> or <% $.fl
85           { %>...</%> or <% $self->floc { %>...</%> or <% $self->fl {
86           %>...</%> are extracted.
87
88       Template Toolkit (plugin: tt2)
89           Valid forms are:
90
91             [% | l(arg1,argn) %]string[% END %]
92             [% 'string' | l(arg1,argn) %]
93             [% l('string',arg1,argn) %]
94
95             FILTER and | are interchangeable
96             l and loc are interchangeable
97             args are optional
98
99       Text::Template (plugin: text)
100           Sentences between "STARTxxx" and "ENDxxx" are extracted
101           individually.
102
103       YAML (plugin: yaml)
104           Valid forms are _"string" or _'string', eg:
105
106               title: _"My title"
107               desc:  _'My "quoted" string'
108
109           Quotes do not have to be escaped, so you could also do:
110
111               desc:  _"My "quoted" string"
112
113       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
117           We extract the text after "_loc: ":
118               content_loc: this is the string
119               message_loc: ['Max string length: [_1]', 10]
120
121       Generic Template (plugin: generic)
122           Strings inside {{...}} are extracted.
123

METHODS

125   Constructor
126           new()
127
128           new(
129               plugins   => {...},
130               warnings  => 1 | 0,
131               verbose   => 0 | 1 | 2 | 3,
132           )
133
134       See "Plugins", "Warnings" and "Verbose" for details
135
136   Plugins
137           $ext->plugins({...});
138
139       Locale::Maketext::Extract uses plugins (see below for the list) to
140       parse different formats.
141
142       Each plugin can also specify which file types it can parse.
143
144           # use only the YAML plugin
145           # only parse files with the default extension list defined in the plugin
146           # ie .yaml .yml .conf
147
148           $ext->plugins({
149               yaml => [],
150           })
151
152
153           # use only the Perl plugin
154           # parse all file types
155
156           $ext->plugins({
157               perl => '*'
158           })
159
160           $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
168           sub my_filter {
169               my ($base_filename,$path_to_file) = @_;
170
171               return 1 | 0;
172           }
173
174           # Specify your own parser
175           # only parse files with the default extension list defined in the plugin
176
177           $ext->plugins({
178               'My::Extract::Parser'  => []
179           })
180
181       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
186       Available plugins
187
188       "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
193       "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
200       Also, see Locale::Maketext::Extract::Plugin::Base for details of how to
201       write your own plugin.
202
203   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
208       The next enabled plugin will be tried.
209
210       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
214       Also, if developing your own plugin, turn on warnings to see any errors
215       that result from loading your plugin.
216
217   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
223             $ext = Locale::Extract->new( verbose => 1 | 2 | 3);
224
225          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
230   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
238   PO File manipulation
239       method read_po ($file)
240
241       method write_po ($file, $add_format_marker?)
242
243   Extraction
244           extract
245           extract_file
246
247   Compilation
248       compile($entries_are_in_gettext_style?)
249
250       Merges the "entries" into "compiled_entries".
251
252       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
255       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
259       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
263       normalize_space
264
265   Lexicon accessors
266           msgids, has_msgid,
267           msgstr, set_msgstr
268           msg_positions, msg_variables, msg_format, msg_out
269
270   Internal utilities
271           _default_header
272           _maketext_to_gettext
273           _escape
274           _format
275           _plugins_specifically_for_file
276

ACKNOWLEDGMENTS

278       Thanks to Jesse Vincent for contributing to an early version of this
279       module.
280
281       Also to Alain Barbet, who effectively re-wrote the source parser with a
282       flex-like algorithm.
283

SEE ALSO

285       xgettext.pl, Locale::Maketext, Locale::Maketext::Lexicon
286

AUTHORS

288       Audrey Tang <cpan@audreyt.org>
289
291       Copyright 2003-2013 by Audrey Tang <cpan@audreyt.org>.
292
293       This software is released under the MIT license cited below.
294
295   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
304       The above copyright notice and this permission notice shall be included
305       in all copies or substantial portions of the Software.
306
307       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

AUTHORS

316       •   Clinton Gormley <drtech@cpan.org>
317
318       •   Audrey Tang <cpan@audreyt.org>
319
321       This software is Copyright (c) 2014 by Audrey Tang.
322
323       This is free software, licensed under:
324
325         The MIT (X11) License
326
327
328
329perl v5.36.0                      2023-01-20      Locale::Maketext::Extract(3)
Impressum