gettext: Interpolation I

1 
1 15.5.18.5 Invalid Uses Of String Interpolation
1 ..............................................
1 
1    Perl is capable of interpolating variables into strings.  This offers
1 some nice features in localized programs but can also lead to problems.
1 
1    A common error is a construct like the following:
1 
1      print gettext "This is the program $0!\n";
1 
1    Perl will interpolate at runtime the value of the variable ‘$0’ into
1 the argument of the ‘gettext()’ function.  Hence, this argument is not a
1 string constant but a variable argument (‘$0’ is a global variable that
1 holds the name of the Perl script being executed).  The interpolation is
1 performed by Perl before the string argument is passed to ‘gettext()’
1 and will therefore depend on the name of the script which can only be
1 determined at runtime.  Consequently, it is almost impossible that a
1 translation can be looked up at runtime (except if, by accident, the
1 interpolated string is found in the message catalog).
1 
1    The ‘xgettext’ program will therefore terminate parsing with a fatal
1 error if it encounters a variable inside of an extracted string.  In
1 general, this will happen for all kinds of string interpolations that
1 cannot be safely performed at compile time.  If you absolutely know what
1 you are doing, you can always circumvent this behavior:
1 
1      my $know_what_i_am_doing = "This is program $0!\n";
1      print gettext $know_what_i_am_doing;
1 
1    Since the parser only recognizes strings and quote-like expressions,
1 but not variables or other terms, the above construct will be accepted.
1 You will have to find another way, however, to let your original string
1 make it into your message catalog.
1 
1    If invoked with the option ‘--extract-all’, resp.  ‘-a’, variable
1 interpolation will be accepted.  Rationale: You will generally use this
1 option in order to prepare your sources for internationalization.
1 
1    Please see the manual page ‘man perlop’ for details of strings and
1 quote-like expressions that are subject to interpolation and those that
1 are not.  Safe interpolations (that will not lead to a fatal error) are:
1 
1    • the escape sequences ‘\t’ (tab, HT, TAB), ‘\n’ (newline, NL), ‘\r’
1      (return, CR), ‘\f’ (form feed, FF), ‘\b’ (backspace, BS), ‘\a’
1      (alarm, bell, BEL), and ‘\e’ (escape, ESC).
1 
1    • octal chars, like ‘\033’
1      Note that octal escapes in the range of 400-777 are translated into
1      a UTF-8 representation, regardless of the presence of the ‘use
1      utf8’ pragma.
1 
1    • hex chars, like ‘\x1b’
1 
1    • wide hex chars, like ‘\x{263a}’
1      Note that this escape is translated into a UTF-8 representation,
1      regardless of the presence of the ‘use utf8’ pragma.
1 
1    • control chars, like ‘\c[’ (CTRL-[)
1 
1    • named Unicode chars, like ‘\N{LATIN CAPITAL LETTER C WITH CEDILLA}’
1 
1      Note that this escape is translated into a UTF-8 representation,
1      regardless of the presence of the ‘use utf8’ pragma.
1 
1    The following escapes are considered partially safe:
1 
1    • ‘\l’ lowercase next char
1 
1    • ‘\u’ uppercase next char
1 
1    • ‘\L’ lowercase till \E
1 
1    • ‘\U’ uppercase till \E
1 
1    • ‘\E’ end case modification
1 
1    • ‘\Q’ quote non-word characters till \E
1 
1    These escapes are only considered safe if the string consists of
1 ASCII characters only.  Translation of characters outside the range
1 defined by ASCII is locale-dependent and can actually only be performed
1 at runtime; ‘xgettext’ doesn’t do these locale-dependent translations at
1 extraction time.
1 
1    Except for the modifier ‘\Q’, these translations, albeit valid, are
1 generally useless and only obfuscate your sources.  If a translation can
1 be safely performed at compile time you can just as well write what you
1 mean.
1