NAME

CallBackery::Translate - gettext po file translation functionality

SYNOPSIS

use CallBackery::Translate qw(mtr);
my $loc = CallBackery::Translate->new(localeRoot=>$dir);
$loc->setLocale('de');
$loc->tra("Hello %1","Tobi");

trm("Mark but for translation but return original");

DESCRIPTION

Read translations from gettext po files and translate incoming data.

setLocale($locale);

Load the translations strings for $locale. First try the full name and then top-up with only the language part.

tra(str[,arg,arg,...])

Translate string into the curent language.

trm(str[,arg,arg,...])

mark for translation but return an array pointer so that the string can be translated dynamically in the frontend.

trm($str[,@args]);

Make string and prepare for translation in the frontend.

Note there is some major perl magic going on! by blessing the returned array into the current package, we then get to use the overload code on stringification AND Mojo::JSON gets to use the TO_JSON method when converting this into something to be transported to the frontend.

An argument may be a trm() of its own, and then it keeps its own msgid all the way to the frontend instead of being rendered here. Use that for a message with an optional part in it -- a warning appended to a confirmation, say -- rather than building the text with .=, which runs the stringification overload and leaves nothing to translate:

my $msg = trm("Settings saved.");
$msg = trm("%1\n\n%2",$msg,$warning) if $warning;

Anything else is stringified as it is passed, so an argument that carries text a user should read in their own language has to be a trm().

trmJoin($sep,@parts);

Join a list of trm() objects into one translatable message.

For a message whose number of parts is only known at run time -- a list of warnings, a set of flags on a table row -- where no single msgid can be written because nobody knows how many placeholders it needs. join() is what one reaches for, and it stringifies every part and destroys their translations.

The msgid this builds holds no words, only placeholders and the separator, so there is nothing in it for a translator to act on; the text stays in the parts, each with its own msgid. Keep $sep free of %, which would be read as a placeholder.

An empty list gives the empty message, and a single part is returned as it is rather than wrapped in a pointless "%1".

$str->TO_JSON

Help Mojo::JSON encode us into JSON.

An ARRAY, always, even when there are no arguments to substitute. The array IS the marker: it is how the frontend tells a string that wants translating from one that is data. Collapsing the no-argument case to a bare string -- which is what this used to do -- made the most common kind of translatable text indistinguishable from a hostname or an error message from some other system, so anything that was not a form label silently stayed in English.

Every consumer in the frontend runs its strings through xtr(), which takes both shapes; the places that did not were the bug.

An argument that is a trm() of its own becomes a nested array, which xtr() resolves before it substitutes. That is how a message built from a fixed part and a couple of optional ones stays translatable in all of its pieces, without a msgid per combination.

COPYRIGHT

Copyright (c) 2010 by OETIKER+PARTNER AG. All rights reserved.

AUTHOR

Tobias Oetiker <tobi@oetiker.ch>

HISTORY

2010-12-22 to 1.0 first version