| 1 | # $Id: Translate.pm 542 2013-12-12 16:36:34Z oetiker $ | ||||||||||||||||||||||||||||
| 2 | package CallBackery::Translate; | ||||||||||||||||||||||||||||
| 3 | |||||||||||||||||||||||||||||
| 4 | 18 | ▶ | use Mojo::Base -base, -signatures; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 5 | 18 | ▶ | use Encode; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 6 | 18 | ▶ | use CallBackery::Exception qw(mkerror); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||
| 8 | 18 | ▶ | use Exporter 'import'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 9 | 18 | ▶ | use vars qw(@EXPORT_OK); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 10 | 18 | @EXPORT_OK = qw(trm trmJoin); | |||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||
| 13 | =head1 NAME | ||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||
| 15 | CallBackery::Translate - gettext po file translation functionality | ||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||
| 17 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||
| 19 | use CallBackery::Translate qw(mtr); | ||||||||||||||||||||||||||||
| 20 | my $loc = CallBackery::Translate->new(localeRoot=>$dir); | ||||||||||||||||||||||||||||
| 21 | $loc->setLocale('de'); | ||||||||||||||||||||||||||||
| 22 | $loc->tra("Hello %1","Tobi"); | ||||||||||||||||||||||||||||
| 23 | |||||||||||||||||||||||||||||
| 24 | trm("Mark but for translation but return original"); | ||||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||
| 26 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 27 | |||||||||||||||||||||||||||||
| 28 | Read translations from gettext po files and translate incoming data. | ||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||
| 30 | =cut | ||||||||||||||||||||||||||||
| 31 | |||||||||||||||||||||||||||||
| 32 | 18 | has 'localeRoot'; | |||||||||||||||||||||||||||
| 33 | |||||||||||||||||||||||||||||
| 34 | =over | ||||||||||||||||||||||||||||
| 35 | |||||||||||||||||||||||||||||
| 36 | =item C<setLocale>($locale); | ||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||
| 38 | Load the translations strings for $locale. First try the full name and | ||||||||||||||||||||||||||||
| 39 | then top-up with only the language part. | ||||||||||||||||||||||||||||
| 40 | |||||||||||||||||||||||||||||
| 41 | =cut | ||||||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||||||
| 43 | 18 | my %lx; | |||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||
| 45 | 2 | ▶ | sub setLocale { | ||||||||||||||||||||||||||
|
Subroutine
setLocale: called CC=11 SCAR=41.5
Pod
documented
| |||||||||||||||||||||||||||||
| 46 | 2 | my $self = shift; | |||||||||||||||||||||||||||
| 47 | 2 | my $locale = shift; | |||||||||||||||||||||||||||
| 48 | 2 | ▶ | if ($lx{$locale}){ | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 49 | 0 | $self->{_lx} = $lx{$locale}; | |||||||||||||||||||||||||||
| 50 | 0 | return; | |||||||||||||||||||||||||||
| 51 | } | ||||||||||||||||||||||||||||
| 52 | 2 | my $lang = $locale; | |||||||||||||||||||||||||||
| 53 | 2 | $lang =~ s/_.+//; | |||||||||||||||||||||||||||
| 54 | 2 | for my $file ($lang,$locale){ | |||||||||||||||||||||||||||
| 55 | 4 | my $mode = 'id'; | |||||||||||||||||||||||||||
| 56 | 4 | ▶ | if (open my $fh, '< :encoding(utf8)', $self->localeRoot.'/'.$file.'.po'){ | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 57 | 0 | my $key; | |||||||||||||||||||||||||||
| 58 | my %var; | ||||||||||||||||||||||||||||
| 59 | 0 | ▶ | while (<$fh>){ | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 60 | 0 | chomp; | |||||||||||||||||||||||||||
| 61 | 0 | ▶ | /^msg(id|str)\s+"(.*)"/ && do { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 62 | 0 | $var{$1} = $2; | |||||||||||||||||||||||||||
| 63 | 0 | $key = $1; | |||||||||||||||||||||||||||
| 64 | 0 | next; | |||||||||||||||||||||||||||
| 65 | }; | ||||||||||||||||||||||||||||
| 66 | 0 | ▶ | /^"(.*)"/ && do { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 67 | 0 | $var{$key} .= $1; | |||||||||||||||||||||||||||
| 68 | 0 | next; | |||||||||||||||||||||||||||
| 69 | }; | ||||||||||||||||||||||||||||
| 70 | 0 | ▶ | /^\s*$/ && $var{id} && do { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition0%0/3
/^\s*$/u and $var{"id"}
MC/DC0%0/2
/^\s*$/u and $var{"id"}
/^\s*$/u
$var{"id"}
Truth table0%0/3
A and B
A= /^\s*$/uB= $var{"id"}
| |||||||||||||||||||||||||||||
| 71 | 0 | $lx{$locale}{$var{id}} = $var{str}; | |||||||||||||||||||||||||||
| 72 | 0 | next; | |||||||||||||||||||||||||||
| 73 | } | ||||||||||||||||||||||||||||
| 74 | } | ||||||||||||||||||||||||||||
| 75 | 0 | ▶ | $lx{$locale}{$var{id}} = $var{str} if $var{id} and $var{str}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition0%0/3
$var{"id"} and $var{"str"}
MC/DC0%0/2
$var{"id"} and $var{"str"}
$var{"id"}
$var{"str"}
Truth table0%0/3
A and B
A= $var{"id"}B= $var{"str"}
| |||||||||||||||||||||||||||||
| 76 | } | ||||||||||||||||||||||||||||
| 77 | } | ||||||||||||||||||||||||||||
| 78 | 2 | $self->{_lx} = $lx{$locale}; | |||||||||||||||||||||||||||
| 79 | } | ||||||||||||||||||||||||||||
| 80 | |||||||||||||||||||||||||||||
| 81 | =item C<tra>(str[,arg,arg,...]) | ||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||
| 83 | Translate string into the curent language. | ||||||||||||||||||||||||||||
| 84 | |||||||||||||||||||||||||||||
| 85 | =cut | ||||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||
| 87 | 27 | ▶ | sub tra { | ||||||||||||||||||||||||||
|
Subroutine
tra: called CC=5 SCAR=16.2
Pod
documented
| |||||||||||||||||||||||||||||
| 88 | 27 | my $self = shift; | |||||||||||||||||||||||||||
| 89 | 27 | my $str = shift; | |||||||||||||||||||||||||||
| 90 | 27 | my @args = @_; | |||||||||||||||||||||||||||
| 91 | 27 | ▶ | my $lx = $self->{_lx} // {}; | ||||||||||||||||||||||||||
|
Condition50%1/2
$self->{"_lx"} // {}
MC/DC0%0/1
$self->{"_lx"} // {}
$self->{"_lx"}
Truth table50%1/2
A
A= $self->{"_lx"}
| |||||||||||||||||||||||||||||
| 92 | 27 | ▶ | $str = $lx->{$str} if $lx->{$str}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 93 | # One pass over the msgid. Substituting the arguments one after the | ||||||||||||||||||||||||||||
| 94 | # other searched the text put in for %1 again for %2, and let %1 match | ||||||||||||||||||||||||||||
| 95 | # the front of %10. A placeholder without an argument stays visible. | ||||||||||||||||||||||||||||
| 96 | 27 | ▶ | $str =~ s{%(\d+)}{$1 >= 1 && $1 <= @args ? $args[$1-1] : "%$1"}eg; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$1 >= 1 and $1 <= @args
MC/DC100%2/2
$1 >= 1 and $1 <= @args
$1 >= 1
$1 <= @args
Truth table100%3/3
A and B
A= $1 >= 1B= $1 <= @args
| |||||||||||||||||||||||||||||
| 97 | 27 | return $str; | |||||||||||||||||||||||||||
| 98 | } | ||||||||||||||||||||||||||||
| 99 | |||||||||||||||||||||||||||||
| 100 | =item C<trm>(str[,arg,arg,...]) | ||||||||||||||||||||||||||||
| 101 | |||||||||||||||||||||||||||||
| 102 | mark for translation but return an array pointer so that the string | ||||||||||||||||||||||||||||
| 103 | can be translated dynamically in the frontend. | ||||||||||||||||||||||||||||
| 104 | |||||||||||||||||||||||||||||
| 105 | =cut | ||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||
| 107 | # trm("Hello %1",$name); | ||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||
| 109 | =head2 trm($str[,@args]); | ||||||||||||||||||||||||||||
| 110 | |||||||||||||||||||||||||||||
| 111 | Make string and prepare for translation in the frontend. | ||||||||||||||||||||||||||||
| 112 | |||||||||||||||||||||||||||||
| 113 | Note there is some major perl magic going on! by blessing the returned | ||||||||||||||||||||||||||||
| 114 | array into the current package, we then get to use the overload code | ||||||||||||||||||||||||||||
| 115 | on stringification AND Mojo::JSON gets to use the TO_JSON method when | ||||||||||||||||||||||||||||
| 116 | converting this into something to be transported to the frontend. | ||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||
| 118 | An argument may be a C<trm()> of its own, and then it keeps its own msgid | ||||||||||||||||||||||||||||
| 119 | all the way to the frontend instead of being rendered here. Use that for a | ||||||||||||||||||||||||||||
| 120 | message with an optional part in it -- a warning appended to a confirmation, | ||||||||||||||||||||||||||||
| 121 | say -- rather than building the text with C<.=>, which runs the | ||||||||||||||||||||||||||||
| 122 | stringification overload and leaves nothing to translate: | ||||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||||
| 124 | my $msg = trm("Settings saved."); | ||||||||||||||||||||||||||||
| 125 | $msg = trm("%1\n\n%2",$msg,$warning) if $warning; | ||||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||
| 127 | Anything else is stringified as it is passed, so an argument that carries | ||||||||||||||||||||||||||||
| 128 | text a user should read in their own language has to be a C<trm()>. | ||||||||||||||||||||||||||||
| 129 | |||||||||||||||||||||||||||||
| 130 | =cut | ||||||||||||||||||||||||||||
| 131 | |||||||||||||||||||||||||||||
| 132 | use overload | ||||||||||||||||||||||||||||
| 133 | 18 | ▶ | '""' => sub ($self,@args) { | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
Subroutine
__ANON__: called CC=3 SCAR=11.2
| |||||||||||||||||||||||||||||
| 134 | # Render the arguments BEFORE substituting them. An argument that is | ||||||||||||||||||||||||||||
| 135 | # itself a trm() runs this very overload, and its own s/// resets $1 | ||||||||||||||||||||||||||||
| 136 | # while the outer s///eg is still walking its string -- which left a | ||||||||||||||||||||||||||||
| 137 | # bare "%1" standing in the result and warned about a non-numeric | ||||||||||||||||||||||||||||
| 138 | # array index. Touching nothing but a plain array in the replacement | ||||||||||||||||||||||||||||
| 139 | # keeps the two substitutions out of each other's way. | ||||||||||||||||||||||||||||
| 140 | 16 | ▶ | my @part = map { defined $_ ? "$_" : '' } @$self; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 141 | 16 | my $ret = $part[0]; | |||||||||||||||||||||||||||
| 142 | 16 | ▶ | $ret =~ s{%(\d+)}{$part[$1]//''}eg; | ||||||||||||||||||||||||||
|
Condition50%1/2
$part[$1] // ""
MC/DC0%0/1
$part[$1] // ""
$part[$1]
Truth table50%1/2
A
A= $part[$1]
| |||||||||||||||||||||||||||||
| 143 | 16 | return $ret; | |||||||||||||||||||||||||||
| 144 | }, | ||||||||||||||||||||||||||||
| 145 | 1 | ▶ | 'eq' => sub ($self,$other,$swap) { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 146 | 1 | return "$self" eq "$other"; | |||||||||||||||||||||||||||
| 147 | 18 | }; | |||||||||||||||||||||||||||
| 148 | |||||||||||||||||||||||||||||
| 149 | 158 | ▶ | sub trm ($str,@args) { | ||||||||||||||||||||||||||
|
Subroutine
trm: called CC=3 SCAR=12.0
Pod
documented
| |||||||||||||||||||||||||||||
| 150 | # make sure the arguments are stringified, warn if undefined | ||||||||||||||||||||||||||||
| 151 | return bless [$str,map { | ||||||||||||||||||||||||||||
| 152 | 158 | ▶ | if (not defined $_) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 153 | 0 | my ($package, $filename, $line) = caller; | |||||||||||||||||||||||||||
| 154 | 0 | warn "Undefined argument for str='$str' from $package line $line"; | |||||||||||||||||||||||||||
| 155 | } | ||||||||||||||||||||||||||||
| 156 | # An argument that is itself a trm() stays an object, so that it | ||||||||||||||||||||||||||||
| 157 | # reaches the frontend as a msgid of its own and gets translated | ||||||||||||||||||||||||||||
| 158 | # there. Stringifying it here -- which is what "$_" below does to | ||||||||||||||||||||||||||||
| 159 | # everything else -- ran the overload, substituted the arguments and | ||||||||||||||||||||||||||||
| 160 | # froze the text in the language of the source code. That is how a | ||||||||||||||||||||||||||||
| 161 | # message assembled from pieces, which is every message with an | ||||||||||||||||||||||||||||
| 162 | # optional part in it, lost its translation. | ||||||||||||||||||||||||||||
| 163 | 28 | ▶ | ref $_ eq __PACKAGE__ ? $_ : "$_" | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 164 | } @args]; | ||||||||||||||||||||||||||||
| 165 | } | ||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||
| 167 | =head2 trmJoin($sep,@parts); | ||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||
| 169 | Join a list of C<trm()> objects into one translatable message. | ||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||
| 171 | For a message whose number of parts is only known at run time -- a list of | ||||||||||||||||||||||||||||
| 172 | warnings, a set of flags on a table row -- where no single msgid can be | ||||||||||||||||||||||||||||
| 173 | written because nobody knows how many placeholders it needs. C<join()> is | ||||||||||||||||||||||||||||
| 174 | what one reaches for, and it stringifies every part and destroys their | ||||||||||||||||||||||||||||
| 175 | translations. | ||||||||||||||||||||||||||||
| 176 | |||||||||||||||||||||||||||||
| 177 | The msgid this builds holds no words, only placeholders and the separator, | ||||||||||||||||||||||||||||
| 178 | so there is nothing in it for a translator to act on; the text stays in the | ||||||||||||||||||||||||||||
| 179 | parts, each with its own msgid. Keep C<$sep> free of C<%>, which would be | ||||||||||||||||||||||||||||
| 180 | read as a placeholder. | ||||||||||||||||||||||||||||
| 181 | |||||||||||||||||||||||||||||
| 182 | An empty list gives the empty message, and a single part is returned as it | ||||||||||||||||||||||||||||
| 183 | is rather than wrapped in a pointless C<"%1">. | ||||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||||
| 185 | =cut | ||||||||||||||||||||||||||||
| 186 | |||||||||||||||||||||||||||||
| 187 | 6 | ▶ | sub trmJoin ($sep,@parts) { | ||||||||||||||||||||||||||
|
Subroutine
trmJoin: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||||||||||||||||||
| 188 | 6 | ▶ | @parts = grep { defined and "$_" ne '' } @parts; | ||||||||||||||||||||||||||
|
Condition100%3/3
defined $_ && "$_" ne ''
MC/DC100%2/2
defined $_ && "$_" ne ''
defined $_
"$_" ne ''
Truth table100%3/3
A && B
A= defined $_B= "$_" ne ''
| |||||||||||||||||||||||||||||
| 189 | 6 | ▶ | return trm('') unless @parts; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 190 | 5 | ▶ | return $parts[0] if @parts == 1 and ref $parts[0] eq __PACKAGE__; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
@parts == 1 and ref $parts[0] eq __PACKAGE__
MC/DC50%1/2
@parts == 1 and ref $parts[0] eq __PACKAGE__
@parts == 1
ref $parts[0] eq __PACKAGE__
Truth table66%2/3
A and B
A= @parts == 1B= ref $parts[0] eq __PACKAGE__
| |||||||||||||||||||||||||||||
| 191 | 4 | return trm(join($sep, map { '%'.($_+1) } 0..$#parts), @parts); | |||||||||||||||||||||||||||
| 192 | } | ||||||||||||||||||||||||||||
| 193 | |||||||||||||||||||||||||||||
| 194 | =head2 $str->TO_JSON | ||||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||||
| 196 | Help L<Mojo::JSON> encode us into JSON. | ||||||||||||||||||||||||||||
| 197 | |||||||||||||||||||||||||||||
| 198 | An ARRAY, always, even when there are no arguments to substitute. The array | ||||||||||||||||||||||||||||
| 199 | IS the marker: it is how the frontend tells a string that wants translating | ||||||||||||||||||||||||||||
| 200 | from one that is data. Collapsing the no-argument case to a bare string -- | ||||||||||||||||||||||||||||
| 201 | which is what this used to do -- made the most common kind of translatable | ||||||||||||||||||||||||||||
| 202 | text indistinguishable from a hostname or an error message from some other | ||||||||||||||||||||||||||||
| 203 | system, so anything that was not a form label silently stayed in English. | ||||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||
| 205 | Every consumer in the frontend runs its strings through C<xtr()>, which takes | ||||||||||||||||||||||||||||
| 206 | both shapes; the places that did not were the bug. | ||||||||||||||||||||||||||||
| 207 | |||||||||||||||||||||||||||||
| 208 | An argument that is a C<trm()> of its own becomes a nested array, which | ||||||||||||||||||||||||||||
| 209 | C<xtr()> resolves before it substitutes. That is how a message built from a | ||||||||||||||||||||||||||||
| 210 | fixed part and a couple of optional ones stays translatable in all of its | ||||||||||||||||||||||||||||
| 211 | pieces, without a msgid per combination. | ||||||||||||||||||||||||||||
| 212 | |||||||||||||||||||||||||||||
| 213 | =cut | ||||||||||||||||||||||||||||
| 214 | |||||||||||||||||||||||||||||
| 215 | 15 | ▶ | sub TO_JSON ($self) { | ||||||||||||||||||||||||||
|
Subroutine
TO_JSON: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 216 | 15 | ▶ | return [map { ref $_ eq __PACKAGE__ ? $_->TO_JSON : $_ } @$self]; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 217 | } | ||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||
| 219 | 18 | 1; | |||||||||||||||||||||||||||
| 220 | |||||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||||
| 222 | __END__ | ||||||||||||||||||||||||||||