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   array  => [ qw(args) ],
  10 );
  11
  12 our @EXPORT = qw(t8);
  13
  14 use overload '""' => \&translated;
  15
  16 sub translated {
  17   my ($self) = @_;
  18   return $::locale ? $::locale->text($self->untranslated, $self->args) : $self->untranslated;
  19 }
  20
  21 sub t8 {
  22   shift if $_[0] eq __PACKAGE__;
  23
  24   my $string = shift;
  25   return SL::Locale::String->new(untranslated => $string, args => \@_);
  26 }
  27
  28 1;
  29 __END__
  30
  31 =pod
  32
  33 =encoding utf8
  34
  35 =head1 NAME
  36
  37 SL::Locale::String - Helper class for translating strings at a later
  38 date (e.g. use at compile time, actual translation during execution
  39 time)
  40
  41 =head1 SYNOPSIS
  42
  43   use SL::Locale::String;
  44
  45   use SL::Controller::Helper::Sorted;
  46
  47   __PACKAGE__->make_sorted(
  48     ...
  49     qty => { title => t8("Quantity") },
  50  );
  51
  52 =head1 OVERVIEW
  53
  54 Every string that should be translated must be recognized by our
  55 translation helper script C<script/locales.pl> somehow. It recognizes
  56 certain function calls as translation instructions and extracts its
  57 arguments for translation by developers/translators.
  58
  59 This works well for calls that occur during execution time: C<<
  60 $::locale->text("Untranslated") >>. However, for untranslated strings
  61 that need to be used at compile time this fails in subtle and not so
  62 subtle ways. If it happens in a module that is C<use>d directly from
  63 the dispatcher then C<$::locale> is not defined and such a call would
  64 end in an error. For modules like controllers that are C<require>d
  65 during execution time it seems to work, but in FastCGI situations this
  66 means that the first call determines the language and all subsequent
  67 calls end up using the same language no matter which language the user
  68 has chosen.
  69
  70 This class solves the issue by providing a small function called L<t8>
  71 which can be used instead of C<< $::locale->text() >>. It is
  72 recognized by C<script/locales.pl>. The untranslated string given to
  73 L<t8> is stored in an instance of C<SL::Locale::String> and translated
  74 only when requested either by calling L<translated> or by
  75 stringification.
  76
  77 Instances of this class can safely be handed over to C<<
  78 $::locale->text() >> which knows how to handle them (and not to
  79 re-translate them).
  80
  81 The function L<t8> is exported by default.
  82
  83 =head1 FUNCTIONS
  84
  85 =head2 EXPORTED FUNCTIONS
  86
  87 =over 4
  88
  89 =item C<t8 $untranslated_string>
  90
  91 Returns a new instance of C<SL::Locale::String> and sets its
  92 L<untranslated> member to C<$untranslated_string>. This function is
  93 exported and cannot be called as a class or instance method.
  94
  95 =back
  96
  97 =head2 INSTANCE FUNCTIONS
  98
  99 =over 4
 100
 101 =item C<untranslated [$new_untranslated]>
 102
 103 Gets or sets the untranslated string.
 104
 105 =item C<translated>
 106
 107 Returns the translated version of the untranslated string. Translation
 108 occurs when this function is called and not when the object instance
 109 is created.
 110
 111 This function is also called during stringification.
 112
 113 =back
 114
 115 =head1 BUGS
 116
 117 Nothing here yet.
 118
 119 =head1 AUTHOR
 120
 121 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 122
 123 =cut