| 1 | #!/usr/bin/perl -w | ||
| 2 | # c.2009 nicholas wehr | ||
| 3 | # $Id: Simple.pm 244 2009-03-31 03:19:32Z nwehr $ | ||
| 4 | |||
| 5 | package Catalyst::Plugin::Localize::Simple; | ||
| 6 | use strict; | ||
| 7 | use warnings; | ||
| 8 | use YAML::Syck; | ||
| 9 | |||
| 10 | our $VERSION = '1.1'; | ||
| 11 | |||
| 12 | =head1 NAME | ||
| 13 | |||
| 14 | Catalyst::Plugin::Localize::Simple | ||
| 15 | |||
| 16 | =head1 SYNOPSIS | ||
| 17 | |||
| 18 | =over 4 | ||
| 19 | |||
| 20 | in MyApp/lib/MyApp.pm | ||
| 21 | |||
| 22 | use Catalyst 'Localize::Simple'; | ||
| 23 | |||
| 24 | in controller | ||
| 25 | |||
| 26 | print $c->localize('de','theking'); | ||
| 27 | |||
| 28 | B<or> harness the power of this module; when you have stored the language preferences in the session | ||
| 29 | |||
| 30 | ... | ||
| 31 | $c->session->{lang} = $c->req->param('language'); | ||
| 32 | ... | ||
| 33 | $c->stash->{bio} = $c->socal('theking'); | ||
| 34 | $c->stash->{template} = $c->socal('welcome.tt2'); | ||
| 35 | ... | ||
| 36 | $c->lang; # the language code | ||
| 37 | |||
| 38 | from a template | ||
| 39 | |||
| 40 | [% c.socal('theking') %] | ||
| 41 | |||
| 42 | <a href="http://www.mysite.com?lang=[% c.lang %]">click here</a> | ||
| 43 | |||
| 44 | =back | ||
| 45 | |||
| 46 | =head1 DESCRIPTION | ||
| 47 | |||
| 48 | This module allows you to setup and access language files very simply by defining dictionary | ||
| 49 | L<YAML> files for configuration. If you're looking for something a little more robust - check | ||
| 50 | out L<Catalyst::Plugin::I18N> and family. The dictionary files are accessed via L<YAML::Syck> | ||
| 51 | to ensure high performance. | ||
| 52 | |||
| 53 | This module intentionally avoids caching the data files to allow for "hot-swapping" of | ||
| 54 | dictionary changes (won't require a Catalyst restart). | ||
| 55 | |||
| 56 | =head1 CONFIGURATION | ||
| 57 | |||
| 58 | __PACKAGE__->config( | ||
| 59 | 'Localize::Simple' => { | ||
| 60 | _sessionkey => 'lang', | ||
| 61 | en => 'root/localize/en.yaml', | ||
| 62 | de => 'root/localize/de.yaml', | ||
| 63 | fr => 'root/localize/fr.yaml', | ||
| 64 | } | ||
| 65 | ); | ||
| 66 | |||
| 67 | =over 4 | ||
| 68 | |||
| 69 | in I<root/localize/en.yaml>... | ||
| 70 | |||
| 71 | --- | ||
| 72 | yes: certainly | ||
| 73 | no: nope | ||
| 74 | welcome.tt2: welcome-en.tt2 | ||
| 75 | theking: Elvis Aaron Presley was an American singer, actor, and musician. | ||
| 76 | |||
| 77 | in I<root/localize/de.yaml>... | ||
| 78 | |||
| 79 | --- | ||
| 80 | yes: ja | ||
| 81 | no: nein | ||
| 82 | welcome.tt2: welcome-de.tt2 | ||
| 83 | theking: Elvis Aron Presley war ein US-amerikanischer Sänger und Schauspieler | ||
| 84 | |||
| 85 | maybe you should put your language files in a consistent location; like this: | ||
| 86 | |||
| 87 | root/ | ||
| 88 | | | ||
| 89 | `-- localize | ||
| 90 | |-- de.yaml | ||
| 91 | |-- en.yaml | ||
| 92 | |-- es.yaml | ||
| 93 | |-- fr.yaml | ||
| 94 | |-- it.yaml | ||
| 95 | `-- ja.yaml | ||
| 96 | |||
| 97 | =back | ||
| 98 | |||
| 99 | =head1 METHODS | ||
| 100 | |||
| 101 | =over 4 | ||
| 102 | |||
| 103 | =item setup (internal Catalyst plugin constructor) | ||
| 104 | |||
| 105 | note: defines a default language 'en' | ||
| 106 | |||
| 107 | =item sessionkey | ||
| 108 | |||
| 109 | this is the session variable that is defined in the configuration file | ||
| 110 | |||
| 111 | note: defines a default key of 'lang' | ||
| 112 | |||
| 113 | =item lang | ||
| 114 | |||
| 115 | returns the language code as stored by your application (into $c->session->{$key} or $c->req->param($key)) | ||
| 116 | |||
| 117 | note: returns the default language 'en' when neither are specified | ||
| 118 | |||
| 119 | =item localize (I<lang>, I<term>) | ||
| 120 | |||
| 121 | =item loc (I<lang>, I<term>) | ||
| 122 | |||
| 123 | this method is the meat and potatoes of this module. it will return the defined I<term> in the dictionary for I<lang>. | ||
| 124 | |||
| 125 | if a term is B<not found>, this method will return a string C<_MISSING_TERM_|term>. I<term> is the term you asked for. | ||
| 126 | this is very handy for tracking down missing terms. | ||
| 127 | |||
| 128 | =item localize_from_session (I<term>) | ||
| 129 | |||
| 130 | =item socal (I<term>) | ||
| 131 | |||
| 132 | this method combines the work of I<lang> and I<localize> into one handy little method call. | ||
| 133 | |||
| 134 | why is it called I<socal>? just a plug for my hometown San Diego, California! ;) | ||
| 135 | |||
| 136 | =back | ||
| 137 | |||
| 138 | =head1 AUTHOR | ||
| 139 | |||
| 140 | Nicholas Wehr C<< <nicholas.wehr@bionikchickens.com> >> | ||
| 141 | |||
| 142 | =head1 LICENSE | ||
| 143 | |||
| 144 | This program is free software; you can redistribute it and/or modify it | ||
| 145 | under the same terms as Perl itself. | ||
| 146 | |||
| 147 | See http://www.perl.com/perl/misc/Artistic.html | ||
| 148 | |||
| 149 | =cut | ||
| 150 | |||
| 151 | # WOW! this code is so neat and clean - there's no need to document anything right? self-explanatory? yes?! yes! | ||
| 152 | |||
| 153 | sub setup { | ||
| 154 | my $self = shift; | ||
| 155 | $self->NEXT::setup(@_); | ||
| 156 | |||
| 157 | unless (defined $self->config->{'Localize::Simple'}) { | ||
| 158 | $self->log->error(sprintf("error loading configuration for: %s", ref $self)); | ||
| 159 | } | ||
| 160 | $self->mk_classdata($_) for qw(sessionkey defaultlanguage); | ||
| 161 | $self->sessionkey( $self->config->{'Localize::Simple'}->{_sessionkey} || 'lang' ); | ||
| 162 | $self->defaultlanguage( $self->config->{'Localize::Simple'}->{_defaultlanguage} || 'en' ); | ||
| 163 | } | ||
| 164 | |||
| 165 | sub lang { | ||
| 166 | my $c = shift; | ||
| 167 | $c->session->{$c->sessionkey} = | ||
| 168 | defined $c->req->param($c->sessionkey) ? $c->req->param($c->sessionkey) : | ||
| 169 | defined $c->session->{$c->sessionkey} ? $c->session->{$c->sessionkey} : | ||
| 170 | $c->defaultlanguage; | ||
| 171 | return $c->session->{$c->sessionkey}; | ||
| 172 | } | ||
| 173 | |||
| 174 | sub localize { | ||
| 175 | my $self = shift; | ||
| 176 | my ($lang, $key) = @_; | ||
| 177 | |||
| 178 | my $map; | ||
| 179 | eval { | ||
| 180 | my $file = $self->config->{'Localize::Simple'}->{$lang}; | ||
| 181 | -e $file or die "file does not exist\n"; | ||
| 182 | $map = LoadFile($file) or die "error loading with YAML::Syck\n"; | ||
| 183 | }; | ||
| 184 | if ($@) { | ||
| 185 | $self->log->error("error loading terms from file: $self->config->{'Localize::Simple'}->{$lang}; $@"); | ||
| 186 | return "_MISSING_TERM_|$key"; | ||
| 187 | } | ||
| 188 | |||
| 189 | my $term = $map->{$key} | ||
| 190 | or $self->log->error("couldn't find [$lang] term for [$key] in file: $self->config->{'Localize::Simple'}->{$lang}"); | ||
| 191 | return $term || "_MISSING_TERM_|$key"; | ||
| 192 | } | ||
| 193 | *loc = \&localize; | ||
| 194 | |||
| 195 | sub localize_from_session { | ||
| 196 | my ($self, $key) = @_; | ||
| 197 | if (my $lang = $self->lang) { | ||
| 198 | return $self->localize($lang, $key); | ||
| 199 | } | ||
| 200 | else { | ||
| 201 | $self->log->error("couldn't determine [lang] session key in session or query params"); | ||
| 202 | return "_MISSING_TERM_|$key"; | ||
| 203 | } | ||
| 204 | } | ||
| 205 | *socal = \&localize_from_session; | ||
| 206 | |||
| 207 | 1; |