SL/Locale/String.pm

   1 package SL::Locale::String;
   2
   3 use strict;
   4
   5 use parent qw(Rose::Object Exporter);
   6
   7 use Rose::Object::MakeMethods::Generic (
   8   scalar => [ qw(untranslated) ],
   9 );
  10
  11 our @EXPORT = qw(t8);
  12
  13 use overload '""' => \&translated;
  14
  15 sub translated {
  16   my ($self) = @_;
  17   return $::locale ? $::locale->text($self->untranslated) : $self->untranslated;
  18 }
  19
  20 sub t8 {
  21   my $string = $_[ ref($_[0]) || ($_[0] eq 'SL::Locale::String') ? 1 : 0 ];
  22   return SL::Locale::String->new(untranslated => $string);
  23 }
  24
  25 1;
  26 __END__
  27
  28 =pod
  29
  30 =encoding utf8
  31
  32 =head1 NAME
  33
  34 SL::Locale::String - Helper class for translating strings at a later
  35 date (e.g. use at compile time, actual translation during execution
  36 time)
  37
  38 =head1 SYNOPSIS
  39
  40   use SL::Locale::String;
  41
  42   use SL::Controller::Helper::Sorted;
  43
  44   __PACKAGE__->make_sorted(
  45     ...
  46     qty => { title => t8("Quantity") },
  47  );
  48
  49 =head1 OVERVIEW
  50
  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.
  55
  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
  65 has chosen.
  66
  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
  72 stringification.
  73
  74 Instances of this class can safely be handed over to C<<
  75 $::locale->text() >> which knows how to handle them (and not to
  76 re-translate them).
  77
  78 The function L<t8> is exported by default.
  79
  80 =head1 FUNCTIONS
  81
  82 =head2 EXPORTED FUNCTIONS
  83
  84 =over 4
  85
  86 =item C<t8 $untranslated_string>
  87
  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.
  91
  92 =back
  93
  94 =head2 INSTANCE FUNCTIONS
  95
  96 =over 4
  97
  98 =item C<untranslated [$new_untranslated]>
  99
 100 Gets or sets the untranslated string.
 101
 102 =item C<translated>
 103
 104 Returns the translated version of the untranslated string. Translation
 105 occurs when this function is called and not when the object instance
 106 is created.
 107
 108 This function is also called during stringification.
 109
 110 =back
 111
 112 =head1 BUGS
 113
 114 Nothing here yet.
 115
 116 =head1 AUTHOR
 117
 118 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 119
 120 =cut