1NAME
2 Locale::Maketext::Lexicon - Use other catalog formats in Maketext
3
4VERSION
5 version 1.00
6
7SYNOPSIS
8 As part of a localization class, automatically glob for available
9 lexicons:
10
11 package Hello::I18N;
12 use base 'Locale::Maketext';
13 use Locale::Maketext::Lexicon {
14 '*' => [Gettext => '/usr/local/share/locale/*/LC_MESSAGES/hello.mo'],
15 ### Uncomment to fallback when a key is missing from lexicons
16 # _auto => 1,
17 ### Uncomment to decode lexicon entries into Unicode strings
18 # _decode => 1,
19 ### Uncomment to load and parse everything right away
20 # _preload => 1,
21 ### Uncomment to use %1 / %quant(%1) instead of [_1] / [quant, _1]
22 # _style => 'gettext',
23 };
24
25 Explicitly specify languages, during compile- or run-time:
26
27 package Hello::I18N;
28 use base 'Locale::Maketext';
29 use Locale::Maketext::Lexicon {
30 de => [Gettext => 'hello_de.po'],
31 fr => [
32 Gettext => 'hello_fr.po',
33 Gettext => 'local/hello/fr.po',
34 ],
35 };
36 # ... incrementally add new lexicons
37 Locale::Maketext::Lexicon->import({
38 de => [Gettext => 'local/hello/de.po'],
39 })
40
41 Alternatively, as part of a localization subclass:
42
43 package Hello::I18N::de;
44 use base 'Hello::I18N';
45 use Locale::Maketext::Lexicon (Gettext => \*DATA);
46 __DATA__
47 # Some sample data
48 msgid ""
49 msgstr ""
50 "Project-Id-Version: Hello 1.3.22.1\n"
51 "MIME-Version: 1.0\n"
52 "Content-Type: text/plain; charset=iso8859-1\n"
53 "Content-Transfer-Encoding: 8bit\n"
54
55 #: Hello.pm:10
56 msgid "Hello, World!"
57 msgstr "Hallo, Welt!"
58
59 #: Hello.pm:11
60 msgid "You have %quant(%1,piece) of mail."
61 msgstr "Sie haben %quant(%1,Poststueck,Poststuecken)."
62
63DESCRIPTION
64 This module provides lexicon-handling modules to read from other
65 localization formats, such as *Gettext*, *Msgcat*, and so on.
66
67 If you are unfamiliar with the concept of lexicon modules, please
68 consult Locale::Maketext and the "webl10n" HTML files in the "docs/"
69 directory of this module.
70
71 A command-line utility xgettext.pl is also installed with this module,
72 for extracting translatable strings from source files.
73
74 The "import" function
75 The "import()" function accepts two forms of arguments:
76
77 (*format* => *source* ... )
78 This form takes any number of argument pairs (usually one); *source*
79 may be a file name, a filehandle, or an array reference.
80
81 For each such pair, it pass the contents specified by the second
82 argument to Locale::Maketext::Lexicon::*format*->parse as a plain
83 list, and export its return value as the %Lexicon hash in the
84 calling package.
85
86 In the case that there are multiple such pairs, the lexicon defined
87 by latter ones overrides earlier ones.
88
89 { *language* => [ *format*, *source* ... ] ... }
90 This form accepts a hash reference. It will export a %Lexicon into
91 the subclasses specified by each *language*, using the process
92 described above. It is designed to alleviate the need to set up a
93 separate subclass for each localized language, and just use the
94 catalog files.
95
96 This module will convert the *language* arguments into lowercase,
97 and replace all "-" with "_", so "zh_TW" and "zh-tw" will both map
98 to the "zh_tw" subclass.
99
100 If *language* begins with "_", it is taken as an option that
101 controls how lexicons are parsed. See "Options" for a list of
102 available options.
103
104 The "*" is a special *language*; it must be used in conjunction with
105 a filename that also contains "*"; all matched files with a valid
106 language code in the place of "*" will be automatically prepared as
107 a lexicon subclass. If there is multiple "*" in the filename, the
108 last one is used as the language name.
109
110 Options
111 "_auto"
112 If set to a true value, missing lookups on lexicons are handled
113 silently, as if an "Auto" lexicon has been appended on all language
114 lexicons.
115
116 "_decode"
117 If set to a true value, source entries will be converted into
118 utf8-strings (available in Perl 5.6.1 or later). This feature needs
119 the Encode or Encode::compat module.
120
121 Currently, only the "Gettext" backend supports this option.
122
123 "_encoding"
124 This option only has effect when "_decode" is set to true. It
125 specifies an encoding to store lexicon entries, instead of
126 utf8-strings.
127
128 If "_encoding" is set to "locale", the encoding from the current
129 locale setting is used.
130
131 "_preload"
132 By default parsing is delayed until first use of the lexicon, set
133 this option to true value to parse it asap. Increment adding
134 lexicons forces parsing.
135
136 Subclassing format handlers
137 If you wish to override how sources specified in different data types
138 are handled, please use a subclass that overrides "lexicon_get_*TYPE*".
139
140 XXX: not documented well enough yet. Patches welcome.
141
142VERSION
143 This document describes version 0.91 of Locale::Maketext::Lexicon.
144
145NOTES
146 When you attempt to localize an entry missing in the lexicon, Maketext
147 will throw an exception by default. To inhibit this behaviour, override
148 the "_AUTO" key in your language subclasses, for example:
149
150 $Hello::I18N::en::Lexicon{_AUTO} = 1; # autocreate missing keys
151
152 If you want to implement a new "Lexicon::*" backend module, please note
153 that "parse()" takes an array containing the source strings from the
154 specified filehandle or filename, which are *not* "chomp"ed. Although if
155 the source is an array reference, its elements will probably not contain
156 any newline characters anyway.
157
158 The "parse()" function should return a hash reference, which will be
159 assigned to the *typeglob* (*Lexicon) of the language module. All it
160 amounts to is that if the returned reference points to a tied hash, the
161 %Lexicon will be aliased to the same tied hash if it was not initialized
162 previously.
163
164ACKNOWLEDGMENTS
165 Thanks to Jesse Vincent for suggesting this module to be written.
166
167 Thanks also to Sean M. Burke for coming up with Locale::Maketext in the
168 first place, and encouraging me to experiment with alternative Lexicon
169 syntaxes.
170
171 Thanks also to Yi Ma Mao for providing the MO file parsing subroutine,
172 as well as inspiring me to implement file globbing and transcoding
173 support.
174
175 See the AUTHORS file in the distribution for a list of people who have
176 sent helpful patches, ideas or comments.
177
178SEE ALSO
179 xgettext.pl for extracting translatable strings from common template
180 systems and perl source files.
181
182 Locale::Maketext, Locale::Maketext::Lexicon::Auto,
183 Locale::Maketext::Lexicon::Gettext, Locale::Maketext::Lexicon::Msgcat,
184 Locale::Maketext::Lexicon::Tie
185
186AUTHORS
187 Audrey Tang <cpan@audreyt.org>
188
189COPYRIGHT
190 Copyright 2002-2013 by Audrey Tang <cpan@audreyt.org>.
191
192 This software is released under the MIT license cited below.
193
194 The "MIT" License
195 Permission is hereby granted, free of charge, to any person obtaining a
196 copy of this software and associated documentation files (the
197 "Software"), to deal in the Software without restriction, including
198 without limitation the rights to use, copy, modify, merge, publish,
199 distribute, sublicense, and/or sell copies of the Software, and to
200 permit persons to whom the Software is furnished to do so, subject to
201 the following conditions:
202
203 The above copyright notice and this permission notice shall be included
204 in all copies or substantial portions of the Software.
205
206 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
207 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
208 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
209 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
210 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
211 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
212 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
213
214AUTHORS
215 * Clinton Gormley <drtech@cpan.org>
216
217 * Audrey Tang <cpan@audreyt.org>
218
219COPYRIGHT AND LICENSE
220 This software is Copyright (c) 2014 by Audrey Tang.
221
222 This is free software, licensed under:
223
224 The MIT (X11) License
225
226