README
1NAME
2 Dancer::Plugin::Lexicon - Flexible I18N using Locale::Maketext::Lexicon
3 for Dancer apps
4
5VERSION
6 version 0.06
7
8SYNOPSIS
9 A language specific sub-class
10 package MyApp::Lexicon::pl;
11
12 sub quant {
13 # Override default plural handling to cope
14 # with the Polish form of plurals, ie:
15 # 1 -> single
16 # 2-4 -> "few"
17 # 5- -> plural
18 }
19
20 Config file
21 plugins:
22 Lexicon:
23 namespace: MyApp::Lexicon
24 path: languages
25 auto_detect: 1
26 default: en
27 func: [l, _]
28 session_name: lang
29 param_name: lang
30 langs:
31 en: "English"
32 en-us: "US English"
33 da: "Dansk"
34 de: "Deutsch"
35 pl: "Polish"
36
37 In your code
38 package MyApp::Handler;
39
40 use Dancer qw(:syntax);
41 use Dancer::Plugin::Lexicon;
42
43 print language;
44 # English
45
46 print language_tag;
47 # en
48
49 my $installed = installed_langs;
50 my $number = keys %$installed;
51
52 print _('I know [quant,_1,language,languages]', $number);
53 # I know 5 languages
54
55 print set_language('fr','de_DE','en');
56 # Deutsch
57
58
59 get '/' => sub {
60 debug "Auto-detected language is ".language;
61
62 };
63
64DESCRIPTION
65 Dancer::Plugin::Lexicon uses Locale::Maketext::Lexicon to provide I18N
66 functionality to your Dancer application.
67
68 Translations are stored in PO or MO (compiled PO) gettext files in the
69 "languages/" dir. You can generate or update your PO files by
70 automatically extracting translatable strings from your code and
71 templates with xgettext.pl.
72
73 It allows you to add language sub-classes which can handle grammatical
74 differences in that language (such as the Polish example given in the
75 "SYNOPSIS").
76
77 The user's preferred language can be auto-detected from their browser
78 settings, and the current language is automatically stored in the user's
79 session. Including "lang=$lang_tag" in the query string change the
80 user's language.
81
82CONFIGURATION
83 namespace
84 The only required configuration is "namespace", which should be the base
85 class in your application that you will use for I18N. The class itself
86 doesn't have to exist, but will be loaded if it does exist:
87
88 plugins:
89 Lexicon:
90 namespace: MyApp::Lexicon
91
92 See "LANGUAGE SUB-CLASSES" for more.
93
94 path
95 The "path" option (default "languages/") allows you to set a different
96 path for where to find your PO files.
97
98 default
99 The default language to use. If not specifified, it defaults to "en".
100 The language must exist in your "languages/" directory. If a translation
101 doesn't exist in the current language, it will be translated using the
102 default language instead.
103
104 langs
105 If not specified, then any PO files in your "languages/" directory will
106 be loaded.
107
108 Alternatively, you can specify a list of language tags:
109
110 langs:
111 en
112 en_US
113 pt
114 pt_BR
115
116 The name of each language will be derived from "name" in
117 I18N::LangTags::List which provides the name in English.
118
119 You can provide your own names as follows:
120
121 langs:
122 en: English
123 en_US: US English
124 de: Deutsch
125 it: Italiano
126
127 A PO file must exist for all listed languages.
128
129 func
130 One or more function names which will be exported to your modules and
131 templates to localize text. For instance:
132
133 func: x
134
135 Would allow you to do:
136
137 x('Localize me')
138
139 And:
140
141 func: [l, _]
142
143 Would allow you to do:
144
145 _('Localize me');
146 l('Localize me');
147
148 session_name
149 The "session_name" param (default "lang") is the session key used to
150 store the user's current language (if sessions are available).
151
152 param_name
153 The "param_name" param (default "lang") is the query string parameter
154 used to change the user's current language.
155
156 auto_detect
157 If you don't want Dancer::Plugin::Lexicon to automatically detect the
158 user's preferred language from their browser headers, then set:
159
160 auto_detect: 0
161
162FUNCTIONS
163 set_language
164 "set_language()" accepts a list of language tags, and chooses the best
165 matching available language. For instance, if you have these languages
166 available: 'en_GB','fr':
167
168 set_language('en_US','en_AU');
169 # British English
170
171 set_language('it','de');
172 # French (closer to Italian)
173
174 If no suitable language is found, then it will set the default language,
175 which you can also force with:
176
177 set_language;
178
179 language
180 The name of the current language as specified in "installed_langs".
181
182 language_tag
183 The language tag of the current language.
184
185 installed_langs
186 A hashref containing all installed languages. The keys are language
187 tags, and the values are the names as specified in your config, or as
188 derived from "name" in I18N::LangTags::List.
189
190 localize
191 The "localize" function will translate the passed in phrase using the
192 current language:
193
194 localize('Translate me', @any_args);
195
196 Also, and functions that you specify in "/func" will also be exported as
197 aliases of "localize"
198
199LANGUAGE SUB-CLASSES
200 No ".pm" files need to exist, but if they do exist, they will be loaded
201 and setup correctly.
202
203 For instance, the class specified in "namespace" (eg "MyClass::Lexicon")
204 is loaded or inflated, and setup to inherit from Locale::Maketext. If
205 you load "fr.po" then it tries to load "MyClass::Lexicon::fr" if it
206 exists, otherwise it inflates it. This class inherits from
207 MyClass::Lexicon.
208
209 If you want to override any functionality for a particular language,
210 then you can create the file "lib/MyClass/Lexicon/fr.pm" and add your
211 overrides in there.
212
213 Also, you could have (eg) "MyClass::Lexicon::pt_br" (Brazilian
214 Portuguese), which is a subclass of "MyClass::Lexicon::pt" (Portuguese).
215 Any translations that aren't found in "pt_br.po" will be looked for in
216 "pt.po", before finally failing over to the default language.
217
218SUPPORT
219 You can find documentation for this module with the perldoc command.
220
221 perldoc Dancer::Plugin::Lexicon
222
223 You can also look for information at:
224
225 * GitHub
226
227 <http://github.com/clintongormley/Dancer-Plugin-Lexicon>
228
229 * CPAN Ratings
230
231 <http://cpanratings.perl.org/d/Dancer-Plugin-Lexicon>
232
233 * Search MetaCPAN
234
235 <https://metacpan.org/module/Dancer::Plugin::Lexicon>
236
237AUTHOR
238 Clinton Gormley <drtech@cpan.org>
239
240COPYRIGHT AND LICENSE
241 This software is copyright (c) 2014 by Clinton Gormley.
242
243 This is free software; you can redistribute it and/or modify it under
244 the same terms as the Perl 5 programming language system itself.
245
246