Debian Codegraph @

lib/Catalyst/Plugin/I18N/Manual.pod

raw
1 =encoding UTF-8
2
3 =head1 NAME
4
5 Catalyst::Plugin::I18N::Manual - (Draft) I18N and L10N with Catalyst and Template Toolkit.
6
7 =head1 OUTLINE
8
9 Prerequisites:
10 - perl >= 5.8.0
11 - Catalyst >= 5.33
12 - Catalyst::Plugin::I18N >= 0.04
13 - Catalyst::Plugin::Unicode >= 0.2
14 - Catlayst::View::TT && Template-Toolkit >= 2.14
15 - GNU gettext utilities
16 - An editor that understands UTF-8 and Byte Order Mark (BOM)
17
18 $ catalyst.pl MyApp
19 created "MyApp"
20 created "MyApp/script"
21 created "MyApp/lib"
22 created "MyApp/root"
23 created "MyApp/root/static"
24 created "MyApp/root/static/images"
25 created "MyApp/t"
26 created "MyApp/lib/MyApp"
27 created "MyApp/lib/MyApp/Model"
28 created "MyApp/lib/MyApp/View"
29 created "MyApp/lib/MyApp/Controller"
30 created "MyApp/lib/MyApp.pm"
31 created "MyApp/Makefile.PL"
32 created "MyApp/README"
33 created "MyApp/Changes"
34 created "MyApp/t/01app.t"
35 created "MyApp/t/02pod.t"
36 created "MyApp/t/03podcoverage.t"
37 created "MyApp/root/static/images/catalyst_logo.png"
38 created "MyApp/root/static/images/btn_120x50_built.png"
39 created "MyApp/root/static/images/btn_120x50_built_shadow.png"
40 created "MyApp/root/static/images/btn_120x50_powered.png"
41 created "MyApp/root/static/images/btn_120x50_powered_shadow.png"
42 created "MyApp/root/static/images/btn_88x31_built.png"
43 created "MyApp/root/static/images/btn_88x31_built_shadow.png"
44 created "MyApp/root/static/images/btn_88x31_powered.png"
45 created "MyApp/root/static/images/btn_88x31_powered_shadow.png"
46 created "MyApp/root/favicon.ico"
47 created "MyApp/script/myapp_cgi.pl"
48 created "MyApp/script/myapp_fastcgi.pl"
49 created "MyApp/script/myapp_server.pl"
50 created "MyApp/script/myapp_test.pl"
51 created "MyApp/script/myapp_create.pl"
52
53 $ cd MyApp
54 $ vim lib/MyApp.pm
55
56 use Catalyst qw/-Debug I18N Unicode/;
57
58 sub begin : Private {
59 my ( $self, $c ) = @_;
60
61 my $locale = $c->request->param('locale');
62
63 $c->response->headers->push_header( 'Vary' => 'Accept-Language' ); # hmm vary and param?
64 $c->languages( $locale ? [ $locale ] : undef );
65 }
66
67 sub default : Private {
68 my ( $self, $c ) = @_;
69
70 my $name = $c->request->param('name') || $c->loc('Guest');
71
72 $c->response->content_type('text/plain; charset=utf-8');
73 $c->response->body( $c->loc( 'Welcome [_1]!', $name ) );
74 }
75
76 $ mkdir lib/MyApp/I18N
77 $ xgettext.pl --output=lib/MyApp/I18N/messages.pot --directory=lib/
78 $ ls lib/MyApp/I18N/
79 messages.pot
80
81 $ msginit --input=lib/MyApp/I18N/messages.pot --output=lib/MyApp/I18N/sv.po --locale=sv
82 Created lib/MyApp/I18N/sv.po.
83
84 $ vim lib/MyApp/I18N/sv.po
85
86 "Content-Type: text/plain; charset=utf-8\n"
87
88 #: lib/MyApp.pm:50
89 msgid "Guest"
90 msgstr "Gäst"
91
92 #. ($name)
93 #: lib/MyApp.pm:54
94 msgid "Welcome %1!"
95 msgstr "Välkommen %1!"
96
97 $ perl script/myapp_server.pl
98 [Fri Dec 2 03:52:45 2005] [catalyst] [debug] Debug messages enabled
99 [Fri Dec 2 03:52:47 2005] [catalyst] [debug] Loaded plugins:
100 .------------------------------------------------------------------------------.
101 | Catalyst::Plugin::I18N |
102 | Catalyst::Plugin::Unicode |
103 '------------------------------------------------------------------------------'
104
105 [Fri Dec 2 03:52:47 2005] [catalyst] [debug] Loaded dispatcher "Catalyst::Dispatcher"
106 [Fri Dec 2 03:52:47 2005] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP"
107 [Fri Dec 2 03:52:47 2005] [catalyst] [debug] Found home "/Users/chansen/MyApp"
108 [Fri Dec 2 03:52:48 2005] [catalyst] [debug] Initialized i18n "MyApp::I18N"
109 [Fri Dec 2 03:52:48 2005] [catalyst] [debug] Loaded Private actions:
110 .----------------------+----------------------------------------+--------------.
111 | Private | Class | Method |
112 +----------------------+----------------------------------------+--------------+
113 | /default | MyApp | default |
114 '----------------------+----------------------------------------+--------------'
115
116 [Fri Dec 2 03:52:48 2005] [catalyst] [info] MyApp powered by Catalyst 5.57
117 You can connect to your server at http://localhost:3000
118
119 # point your browser to http://localhost:3000/?name=Joe
120 # output should render:
121
122 Välkommen Joe!
123
124 $ vim lib/MyApp.pm
125
126 sub default : Private {
127
128 # ...
129
130 $c->response->body( $c->loc( 'Welcome to my homepage [_1]!', $name ) );
131 }
132
133 $ xgettext.pl --output=lib/MyApp/I18N/messages.pot --directory=lib/
134 $ msgmerge --update lib/MyApp/I18N/sv.po lib/MyApp/I18N/messages.pot
135 . done.
136
137 $ vim lib/MyApp/I18N/sv.po
138
139 #. ($name)
140 #: lib/MyApp.pm:54
141 msgid "Welcome to my homepage %1!"
142 msgstr "Välkommen till min hemsida %1!"
143
144 $ perl script/myapp_server.pl
145
146 # point your browser to http://localhost:3000/?name=Joe
147 # output should render:
148
149 Välkommen till min hemsida Joe!
150
151 $ perl script/myapp_create.pl view TT TT
152 exists "/Users/chansen/MyApp/script/../lib/MyApp/View"
153 exists "/Users/chansen/MyApp/script/../t"
154 created "/Users/chansen/MyApp/script/../lib/MyApp/View/TT.pm"
155 created "/Users/chansen/MyApp/script/../t/view_TT.t"
156
157 $ vim lib/MyApp.pm
158
159 sub default : Private {
160 my ( $self, $c ) = @_;
161
162 my $name = $c->request->param('name') || $c->loc('Guest');
163
164 $c->response->content_type('text/plain; charset=utf-8');
165 $c->stash(
166 name => $name,
167 template => 'test.tt'
168 );
169
170 $c->forward('MyApp::View::TT');
171 }
172
173 $ vim root/test.tt # Save file in UTF-8 with BOM
174
175 [% c.loc( 'Welcome to my place [_1]!', c.stash.name ) %]
176
177 $ xgettext.pl --output=lib/MyApp/I18N/messages.pot --directory=lib/ --directory=root/
178 $ msgmerge --update lib/MyApp/I18N/sv.po lib/MyApp/I18N/messages.pot
179 . done.
180
181 $ vim lib/MyApp/I18N/sv.po
182
183 #. (c.stash.name)
184 #: root/test.tt:1
185 msgid "Welcome to my place %1!"
186 msgstr "Välkommen till mitt ställe %1!"
187
188 $ perl script/myapp_server.pl
189 [Fri Dec 2 05:12:58 2005] [catalyst] [debug] Debug messages enabled
190 [Fri Dec 2 05:12:58 2005] [catalyst] [debug] Loaded plugins:
191 .------------------------------------------------------------------------------.
192 | Catalyst::Plugin::I18N |
193 | Catalyst::Plugin::Unicode |
194 '------------------------------------------------------------------------------'
195
196 [Fri Dec 2 05:12:58 2005] [catalyst] [debug] Loaded dispatcher "Catalyst::Dispatcher"
197 [Fri Dec 2 05:12:58 2005] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP"
198 [Fri Dec 2 05:12:58 2005] [catalyst] [debug] Found home "/Users/chansen/MyApp"
199 [Fri Dec 2 05:12:58 2005] [catalyst] [debug] Initialized i18n "MyApp::I18N"
200 [Fri Dec 2 05:12:59 2005] [catalyst] [debug] Loaded components:
201 .-------------------------------------------------------------------+----------.
202 | Class | Type |
203 +-------------------------------------------------------------------+----------+
204 | MyApp::View::TT | instance |
205 '-------------------------------------------------------------------+----------'
206
207 [Fri Dec 2 05:12:59 2005] [catalyst] [debug] Loaded Private actions:
208 .----------------------+----------------------------------------+--------------.
209 | Private | Class | Method |
210 +----------------------+----------------------------------------+--------------+
211 | /default | MyApp | default |
212 '----------------------+----------------------------------------+--------------'
213
214 [Fri Dec 2 05:12:59 2005] [catalyst] [info] MyApp powered by Catalyst 5.57
215 You can connect to your server at http://localhost:3000
216
217 # point your browser to http://localhost:3000/?name=Joe
218 # output should render:
219
220 Välkommen till mitt ställe Joe!
221
222
223 =head1 INTRODUCTION
224
225 =head1 INTERNATIONALIZATION
226
227 =head1 CONTENT NEGOTIATION
228
229 =head2 Server-driven
230
231 =head2 Agent-driven
232
233 =head1 LOCALIZATION
234
235 =head1 STAYING IN SYNC
236
237 =head1 TEMPLATE TOOLKIT
238
239 =head1 RESOURCES
240
241 =head2 Documentation
242
243 =head3 Definitions
244
245 =over 4
246
247 =item Internationalization and localization
248
249 L<http://en.wikipedia.org/wiki/Internationalization_and_localization>
250
251 =item Locale
252
253 L<http://en.wikipedia.org/wiki/Locale>
254
255 =item Byte Order Mark (BOM)
256
257 L<http://en.wikipedia.org/wiki/Byte_Order_Mark>
258
259 =item Character encoding
260
261 L<http://en.wikipedia.org/wiki/Character_encoding>
262
263 =item Collation
264
265 L<http://en.wikipedia.org/wiki/Collation>
266
267 =item Content Negotiation
268
269 L<http://en.wikipedia.org/wiki/Content_Negotiation>
270
271 =item Unicode
272
273 L<http://en.wikipedia.org/wiki/Unicode>
274
275 =back
276
277 =head3 Guides
278
279 =over 4
280
281 =item Guidelines, Checklists, and Resources
282
283 L<http://www.i18nguy.com/guidelines.html>
284
285 =item Localisation Guide
286
287 L<http://translate.sourceforge.net/wiki/guide/start>
288
289 =back
290
291 =head3 Perl
292
293 =over 4
294
295 =item Perl Locale handling
296
297 L<http://search.cpan.org/dist/perl/pod/perllocale.pod>
298
299 =item Perl Unicode introduction
300
301 L<http://search.cpan.org/dist/perl/pod/perluniintro.pod>
302
303 =item Perl Unicode support
304
305 L<http://search.cpan.org/dist/perl/pod/perlunicode.pod>
306
307 =item Unicode-processing issues in Perl and how to cope with it
308
309 L<http://www.ahinea.com/en/tech/perl-unicode-struggle.html>
310
311 =item Web Localization in Perl
312
313 L<http://search.cpan.org/dist/Locale-Maketext-Lexicon/docs/webl10n.html>
314
315 =item Localization and Perl: gettext breaks, Maketext fixes
316
317 L<http://search.cpan.org/dist/Locale-Maketext/lib/Locale/Maketext/TPJ13.pod>
318
319 =item Lessons Learned with Perl and UTF-8
320
321 L<http://www.justatheory.com/computers/programming/perl/utf8_trials.html>
322
323 =item UTF-8 and Perl (In Five Minutes)
324
325 Slides from a talk given by Mark Fowler.
326
327 L<http://www.twoshortplanks.com/talks/utf8/perlandutf8.pdf>
328
329 =item Perl Loves UTF-8
330
331 Slides from a talk given by Tom Insam.
332
333 L<http://jerakeen.org/slush/talk-perl-loves-utf8>
334
335 =item Perl I18N Mailing List
336
337 L<http://lists.cpan.org/showlist.cgi?name=perl-i18n>
338
339 =item Perl Unicode Mailing List
340
341 L<http://lists.cpan.org/showlist.cgi?name=perl-unicode>
342
343 =back
344
345 =head3 Portals
346
347 =over 4
348
349 =item Google Directory - Computers > Software > Globalization
350
351 L<http://www.google.com/Top/Computers/Software/Globalization/>
352
353 =item Internationalization (I18N), Localization (L10N), Standards, and Amusements
354
355 L<http://www.i18nguy.com/>
356
357 =back
358
359 =head3 Standards
360
361 =over 4
362
363 =item RFC 2616 Hypertext Transfer Protocol -- HTTP/1.1
364
365 L<http://www.w3.org/Protocols/rfc2616/rfc2616.html>
366
367 =over 8
368
369 =item Section 12: Content Negotiation
370
371 L<http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12>
372
373 =item Section 13: Caching in HTTP
374
375 L<http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13>
376
377 =item Section 13.6: Caching Negotiated Responses
378
379 L<http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.6>
380
381 =back
382
383 =item RFC 3066 Tags for the Identification of Languages
384
385 L<http://www.faqs.org/rfcs/rfc3066.html>
386
387 =back
388
389 =head3 Web
390
391 =over 4
392
393 =item W3C Internationalization (I18N) Activity
394
395 L<http://www.w3.org/International/>
396
397 =item Authoring Techniques for XHTML & HTML Internationalization: Characters and Encodings 1.0
398
399 L<http://www.w3.org/TR/i18n-html-tech-char/>
400
401 =item Authoring Techniques for XHTML & HTML Internationalization: Specifying the language of content 1.0
402
403 L<http://www.w3.org/TR/i18n-html-tech-lang/>
404
405 =back
406
407 =head2 Locale Repositories
408
409 =over 4
410
411 =item Common Locale Data Repository (CLDR)
412
413 L<http://www.unicode.org/cldr/>
414
415 =item International Components for Unicode (ICU)
416
417 L<http://www-306.ibm.com/software/globalization/icu/index.jsp>
418
419 =back
420
421 =head2 Modules
422
423 =head3 Character Encoding, Collation and Normalization
424
425 =over 4
426
427 =item Encode
428
429 L<http://search.cpan.org/dist/Encode/>
430
431 =item Unicode::Collate
432
433 L<http://search.cpan.org/dist/Unicode-Collate/>
434
435 =item Unicode::Normalize
436
437 L<http://search.cpan.org/dist/Unicode-Normalize/>
438
439 =back
440
441 =head3 Currency
442
443 =over 4
444
445 =item Locale::Currency::Format
446
447 L<http://search.cpan.org/dist/Locale-Currency-Format/>
448
449 =item Math::Currency
450
451 L<http://search.cpan.org/dist/Math-Currency/>
452
453 =back
454
455 =head3 Dates
456
457 =over 4
458
459 =item DateTime
460
461 L<http://search.cpan.org/dist/DateTime/>
462
463 =item DateTime::Locale
464
465 L<http://search.cpan.org/dist/DateTime-Locale/>
466
467 =item DateTime::TimeZone
468
469 L<http://search.cpan.org/dist/DateTime-TimeZone/>
470
471 =back
472
473 =head3 Language Tags, Identification and Negotiation
474
475 =over 4
476
477 =item HTTP::Negotiate
478
479 L<http://search.cpan.org/dist/libwww-perl/lib/HTTP/Negotiate.pm>
480
481 =item I18N::AcceptLanguage
482
483 L<http://search.cpan.org/dist/I18N-AcceptLanguage/>
484
485 =item I18N::LangTags
486
487 L<http://search.cpan.org/dist/I18N-LangTags/>
488
489 L<http://search.cpan.org/dist/I18N-LangTags/lib/I18N/LangTags/Detect.pm>
490
491 =back
492
493 =head3 Message Catalogs
494
495 =over 4
496
497 =item Locale::Maketext
498
499 L<http://search.cpan.org/dist/Locale-Maketext/>
500
501 L<http://search.cpan.org/dist/Locale-Maketext/lib/Locale/Maketext/TPJ13.pod>
502
503 =item Locale::Maketext::Lexicon
504
505 L<http://search.cpan.org/dist/Locale-Maketext-Lexicon/>
506
507 L<http://search.cpan.org/dist/Locale-Maketext-Lexicon/docs/webl10n.html>
508
509 L<http://search.cpan.org/dist/Locale-Maketext-Lexicon/script/xgettext.pl>
510
511 =item Locale::Maketext::Simple
512
513 Provides a simple interface to Locale::Maketext::Lexicon.
514
515 L<http://search.cpan.org/dist/Locale-Maketext-Simple/>
516
517 =item libintl-perl
518
519 L<http://search.cpan.org/dist/libintl-perl/lib/Locale/Messages.pm>
520
521 L<http://search.cpan.org/dist/libintl-perl/lib/Locale/TextDomain.pm>
522
523 =back
524
525 =head3 Numbers
526
527 =over 4
528
529 =item Number::Format
530
531 L<http://search.cpan.org/dist/Number-Format/>
532
533 =back
534
535 =head2 Tools
536
537 =over 4
538
539 =item GNU gettext utilities
540
541 L<http://www.gnu.org/software/gettext/>
542
543 L<http://www.gnu.org/software/gettext/manual/html_chapter/gettext.html>
544
545 L<http://gnuwin32.sourceforge.net/packages/gettext.htm>
546
547 =item gtranslator
548
549 Translation tool for Gnome. Supports gettext catalogs.
550
551 L<http://gtranslator.sourceforge.net/>
552
553 =item Ini Translator
554
555 Translation tool for Windows 98/Me/XP/2000. Supports several formats,
556 including gettext catalogs.
557
558 L<http://initranslator.sourceforge.net/>
559
560 =item KBabel
561
562 Translation tool for KDE. Supports gettext catalogs.
563
564 L<http://i18n.kde.org/tools/kbabel/>
565
566 =item LocFactory Editor
567
568 Translation tool for Mac OS X. Supports sevral formats, including gettext
569 catalogs.
570
571 L<http://www.triplespin.com/en/products/locfactoryeditor.html>
572
573 =item poEdit
574
575 A cross-platform gettext catalogs editor.
576
577 L<http://www.poedit.org/>
578
579 =back
580
581 =head1 AUTHOR
582
583 Christian Hansen C<[email protected]>
584
585 =head1 COPYRIGHT
586
587 This program is free software, you can redistribute it and/or modify
588 it under the same terms as Perl itself.
589
590 =cut