rt/docs/design_docs/string-extraction-guide.txt

   1 # $File: //depot/RT/rt-devel/docs/design_docs/string-extraction-guide.txt $ $Author: ivan $
   2 # $Revision: 1.1.1.2 $ $Change: 1431 $ $DateTime: 2002/10/15 17:24:45 $
   3
   4 Run 'p4 edit lib/RT/I18N/zh_tw.pm' and 'perl l10n.pl' to add new
   5 extractions to the zh_tw.pm.
   6
   7 Edit lib/RT/I18N/zh_tw.pm for chinese counterparts.
   8
   9 Attached is a copy of the freshly rewritten string extraction style guide.
  10 Please point out anything that's unclear or underspecified.   I
  11 localized a number of the core modules in RT 2.1.3 (Starting with
  12 Queue_Overlay.pm). I only touched a couple of the web templates in the
  13 Elements/ directory of the web ui.
  14
  15 RT String extraction styleguide:
  16
  17 Web templates:
  18
  19 Templates should use the /l filtering component to call the localisation
  20 framework
  21
  22 The string              Foo!
  23
  24 Should become           <&|/l&>Foo!</&>
  25
  26 All newlines should be removed from localized strings, to make it easy to
  27 grep the codebase for strings to be localized
  28
  29 The string              Foo
  30                         Bar
  31                         Baz
  32
  33 Should become           <&|/l&>Foo Bar Baz</&>
  34
  35
  36 Variable subsititutions should be moved to Locale::MakeText format
  37
  38 The string              Hello, <%$name %>
  39
  40 should become           <&|/l, $name &>Hello, [_1]</&>
  41
  42
  43 Multiple variables work just like single variables
  44
  45 The string              You found <%$num%> tickets in queue <%$queue%>
  46
  47 should become           <&|/l, $num, $queue &>You found [_1] tickets in queue [_2]</&>
  48
  49 When subcomponents are called in the middle of a phrase, they need to be escaped
  50 too:
  51
  52 The string               <input type="submit" value="New ticket in">&nbsp<& /Elements/SelectNewTicketQueue&>
  53
  54 should become           <&|/l, $m->scomp('/Elements/SelectNewTicketQueue')&><input type="submit" value="New ticket in">&nbsp;[_1]</&>
  55
  56
  57
  58 There are places inside the web ui where strings are defined, which need to be
  59 localised. it is important to note here that each localized string is split out
  60 onto its own line, but never split across two lines and two localized strings
  61 are never included on the same line. It is also important to note
  62 that this will genereate code which will not work in RT 2.1.3. I need
  63 to add a bit of framework to make it work in 2.1.4
  64
  65
  66 The string      <& /Widgets/TitleBoxStart, width=> "40%", titleright => "RT $RT::VERSION for ". RT->Config->Get('rtname'), title => 'Login' &>
  67
  68 should become   <& /Widgets/TitleBoxStart,
  69                         width=> "40%",
  70                         titleright => loc("RT [_1] for [_2]",$RT::VERSION, RT->Config->Get('rtname')),
  71                         title => loc('Login'),
  72                 &>
  73
  74
  75
  76
  77
  78
  79 Within RT's core code, every module has a localization handle available through the 'loc' method:
  80
  81 The code        return ( $id, "Queue created" );
  82
  83 should become   return ( $id, $self->loc("Queue created") );
  84
  85 When returning or localizing a single string, the "extra" set of parenthesis () should be omitted.
  86
  87 The code        return ("Subject changed to ". $self->Data );
  88
  89 should become    return $self->loc( "Subject changed to [_1]", $self->Data );
  90
  91
  92 It is important not to localize  the names of rights or statuses within RT's core, as there is logic that depends on them as string identifiers.  The proper place to localize these values is when they're presented for display in the web or commandline interfaces.
  93
  94
  95
  96
  97
  98 --
  99 http://www.bestpractical.com/products/rt  -- Trouble Ticketing. Free.
 100