Locale::Maketext::Lexicon(3pm)

1Locale::Maketext::LexicUosne(r3)Contributed Perl DocumenLtoactailoen::Maketext::Lexicon(3)
2
3
4

NAME

6       Locale::Maketext::Lexicon - Use other catalog formats in Maketext
7

VERSION

9       This document describes version 0.80 of Locale::Maketext::Lexicon,
10       released December 29, 2008.
11

SYNOPSIS

13       As part of a localization class, automatically glob for available
14       lexicons:
15
16           package Hello::I18N;
17           use base 'Locale::Maketext';
18           use Locale::Maketext::Lexicon {
19               '*' => [Gettext => '/usr/local/share/locale/*/LC_MESSAGES/hello.mo'],
20               ### Uncomment to fallback when a key is missing from lexicons
21               # _auto   => 1,
22               ### Uncomment to decode lexicon entries into Unicode strings
23               # _decode => 1,
24               ### Uncomment to load and parse everything right away
25               # _preload => 1,
26               ### Uncomment to use %1 / %quant(%1) instead of [_1] / [quant, _1]
27               # _style  => 'gettext',
28           };
29
30       Explicitly specify languages, during compile- or run-time:
31
32           package Hello::I18N;
33           use base 'Locale::Maketext';
34           use Locale::Maketext::Lexicon {
35               de => [Gettext => 'hello_de.po'],
36               fr => [
37                   Gettext => 'hello_fr.po',
38                   Gettext => 'local/hello/fr.po',
39               ],
40           };
41           # ... incrementally add new lexicons
42           Locale::Maketext::Lexicon->import({
43               de => [Gettext => 'local/hello/de.po'],
44           })
45
46       Alternatively, as part of a localization subclass:
47
48           package Hello::I18N::de;
49           use base 'Hello::I18N';
50           use Locale::Maketext::Lexicon (Gettext => \*DATA);
51           __DATA__
52           # Some sample data
53           msgid ""
54           msgstr ""
55           "Project-Id-Version: Hello 1.3.22.1\n"
56           "MIME-Version: 1.0\n"
57           "Content-Type: text/plain; charset=iso8859-1\n"
58           "Content-Transfer-Encoding: 8bit\n"
59
60           #: Hello.pm:10
61           msgid "Hello, World!"
62           msgstr "Hallo, Welt!"
63
64           #: Hello.pm:11
65           msgid "You have %quant(%1,piece) of mail."
66           msgstr "Sie haben %quant(%1,Poststueck,Poststuecken)."
67

DESCRIPTION

69       This module provides lexicon-handling modules to read from other
70       localization formats, such as Gettext, Msgcat, and so on.
71
72       If you are unfamiliar with the concept of lexicon modules, please
73       consult Locale::Maketext and the "webl10n" HTML files in the "docs/"
74       directory of this module.
75
76       A command-line utility xgettext.pl is also installed with this module,
77       for extracting translatable strings from source files.
78
79   The "import" function
80       The "import()" function accepts two forms of arguments:
81
82       (format => source ... )
83           This form takes any number of argument pairs (usually one); source
84           may be a file name, a filehandle, or an array reference.
85
86           For each such pair, it pass the contents specified by the second
87           argument to Locale::Maketext::Lexicon::format->parse as a plain
88           list, and export its return value as the %Lexicon hash in the
89           calling package.
90
91           In the case that there are multiple such pairs, the lexicon defined
92           by latter ones overrides earlier ones.
93
94       { language => [ format, source ... ] ... }
95           This form accepts a hash reference.  It will export a %Lexicon into
96           the subclasses specified by each language, using the process
97           described above.  It is designed to alleviate the need to set up a
98           separate subclass for each localized language, and just use the
99           catalog files.
100
101           This module will convert the language arguments into lowercase, and
102           replace all "-" with "_", so "zh_TW" and "zh-tw" will both map to
103           the "zh_tw" subclass.
104
105           If language begins with "_", it is taken as an option that controls
106           how lexicons are parsed.  See "Options" for a list of available
107           options.
108
109           The "*" is a special language; it must be used in conjunction with
110           a filename that also contains "*"; all matched files with a valid
111           language code in the place of "*" will be automatically prepared as
112           a lexicon subclass.  If there is multiple "*" in the filename, the
113           last one is used as the language name.
114
115   Options
116       "_auto"
117           If set to a true value, missing lookups on lexicons are handled
118           silently, as if an "Auto" lexicon has been appended on all language
119           lexicons.
120
121       "_decode"
122           If set to a true value, source entries will be converted into
123           utf8-strings (available in Perl 5.6.1 or later).  This feature
124           needs the Encode or Encode::compat module.
125
126           Currently, only the "Gettext" backend supports this option.
127
128       "_encoding"
129           This option only has effect when "_decode" is set to true.  It
130           specifies an encoding to store lexicon entries, instead of
131           utf8-strings.
132
133           If "_encoding" is set to "locale", the encoding from the current
134           locale setting is used.
135
136       "_preload"
137           By default parsing is delayed until first use of the lexicon, set
138           this option to true value to parse it asap. Increment adding
139           lexicons forces parsing.
140
141   Subclassing format handlers
142       If you wish to override how sources specified in different data types
143       are handled, please use a subclass that overrides "lexicon_get_TYPE".
144
145       XXX: not documented well enough yet.  Patches welcome.
146

NOTES

148       When you attempt to localize an entry missing in the lexicon, Maketext
149       will throw an exception by default.  To inhibit this behaviour,
150       override the "_AUTO" key in your language subclasses, for example:
151
152           $Hello::I18N::en::Lexicon{_AUTO} = 1; # autocreate missing keys
153
154       If you want to implement a new "Lexicon::*" backend module, please note
155       that "parse()" takes an array containing the source strings from the
156       specified filehandle or filename, which are not "chomp"ed.  Although if
157       the source is an array reference, its elements will probably not
158       contain any newline characters anyway.
159
160       The "parse()" function should return a hash reference, which will be
161       assigned to the typeglob (*Lexicon) of the language module.  All it
162       amounts to is that if the returned reference points to a tied hash, the
163       %Lexicon will be aliased to the same tied hash if it was not
164       initialized previously.
165

ACKNOWLEDGMENTS

167       Thanks to Jesse Vincent for suggesting this module to be written.
168
169       Thanks also to Sean M. Burke for coming up with Locale::Maketext in the
170       first place, and encouraging me to experiment with alternative Lexicon
171       syntaxes.
172
173       Thanks also to Yi Ma Mao for providing the MO file parsing subroutine,
174       as well as inspiring me to implement file globbing and transcoding
175       support.
176
177       See the AUTHORS file in the distribution for a list of people who have
178       sent helpful patches, ideas or comments.
179

AUTHORS

189       Audrey Tang <cpan@audreyt.org>
190

COPYRIGHT

192       Copyright 2002-2008 by Audrey Tang <cpan@audreyt.org>.
193
194       This software is released under the MIT license cited below.
195
196   The "MIT" License
197       Permission is hereby granted, free of charge, to any person obtaining a
198       copy of this software and associated documentation files (the
199       "Software"), to deal in the Software without restriction, including
200       without limitation the rights to use, copy, modify, merge, publish,
201       distribute, sublicense, and/or sell copies of the Software, and to
202       permit persons to whom the Software is furnished to do so, subject to
203       the following conditions:
204
205       The above copyright notice and this permission notice shall be included
206       in all copies or substantial portions of the Software.
207
208       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
209       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
210       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
211       IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
212       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
213       TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
214       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
215
216
217
218perl v5.12.2                      2010-12-24      Locale::Maketext::Lexicon(3)