1 package SL::Locale::String;
5 use parent qw(Rose::Object Exporter);
7 use Rose::Object::MakeMethods::Generic (
8 scalar => [ qw(untranslated) ],
13 use overload '""' => \&translated;
17 return $::locale ? $::locale->text($self->untranslated) : $self->untranslated;
21 my $string = $_[ ref($_[0]) || ($_[0] eq 'SL::Locale::String') ? 1 : 0 ];
22 return SL::Locale::String->new(untranslated => $string);
34 SL::Locale::String - Helper class for translating strings at a later
35 date (e.g. use at compile time, actual translation during execution
40 use SL::Locale::String;
42 use SL::Controller::Helper::Sorted;
44 __PACKAGE__->make_sorted(
46 qty => { title => t8("Quantity") },
51 Every string that should be translated must be recognized by our
52 translation helper script C<script/locales.pl> somehow. It recognizes
53 certain function calls as translation instructions and extracts its
54 arguments for translation by developers/translators.
56 This works well for calls that occur during execution time: C<<
57 $::locale->text("Untranslated") >>. However, for untranslated strings
58 that need to be used at compile time this fails in subtle and not so
59 subtle ways. If it happens in a module that is C<use>d directly from
60 the dispatcher then C<$::locale> is not defined and such a call would
61 end in an error. For modules like controllers that are C<require>d
62 during execution time it seems to work, but in FastCGI situations this
63 means that the first call determines the language and all subsequent
64 calls end up using the same language no matter which language the user
67 This class solves the issue by providing a small function called L<t8>
68 which can be used instead of C<< $::locale->text() >>. It is
69 recognized by C<script/locales.pl>. The untranslated string given to
70 L<t8> is stored in an instance of C<SL::Locale::String> and translated
71 only when requested either by calling L<translated> or by
74 Instances of this class can safely be handed over to C<<
75 $::locale->text() >> which knows how to handle them (and not to
78 The function L<t8> is exported by default.
82 =head2 EXPORTED FUNCTIONS
86 =item C<t8 $untranslated_string>
88 Returns a new instance of C<SL::Locale::String> and sets its
89 L<untranslated> member to C<$untranslated_string>. This function is
90 exported and cannot be called as a class or instance method.
94 =head2 INSTANCE FUNCTIONS
98 =item C<untranslated [$new_untranslated]>
100 Gets or sets the untranslated string.
104 Returns the translated version of the untranslated string. Translation
105 occurs when this function is called and not when the object instance
108 This function is also called during stringification.
118 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>