| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Locale::Maketext 3perl" |
| 58 |
.TH Locale::Maketext 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Locale::Maketext \- framework for localization |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 9 |
| 68 |
\& package MyProgram; |
| 69 |
\& use strict; |
| 70 |
\& use MyProgram::L10N; |
| 71 |
\& # ...which inherits from Locale::Maketext |
| 72 |
\& my $lh = MyProgram::L10N\->get_handle() || die "What language?"; |
| 73 |
\& ... |
| 74 |
\& # And then any messages your program emits, like: |
| 75 |
\& warn $lh\->maketext( "Can\*(Aqt open file [_1]: [_2]\en", $f, $! ); |
| 76 |
\& ... |
| 77 |
.Ve |
| 78 |
.SH DESCRIPTION |
| 79 |
.IX Header "DESCRIPTION" |
| 80 |
It is a common feature of applications (whether run directly, |
| 81 |
or via the Web) for them to be "localized" \-\- i.e., for them |
| 82 |
to a present an English interface to an English-speaker, a German |
| 83 |
interface to a German-speaker, and so on for all languages it's |
| 84 |
programmed with. Locale::Maketext |
| 85 |
is a framework for software localization; it provides you with the |
| 86 |
tools for organizing and accessing the bits of text and text-processing |
| 87 |
code that you need for producing localized applications. |
| 88 |
.PP |
| 89 |
In order to make sense of Maketext and how all its |
| 90 |
components fit together, you should probably |
| 91 |
go read Locale::Maketext::TPJ13, and |
| 92 |
\&\fIthen\fR read the following documentation. |
| 93 |
.PP |
| 94 |
You may also want to read over the source for \f(CW\*(C`File::Findgrep\*(C'\fR |
| 95 |
and its constituent modules \-\- they are a complete (if small) |
| 96 |
example application that uses Maketext. |
| 97 |
.SH "QUICK OVERVIEW" |
| 98 |
.IX Header "QUICK OVERVIEW" |
| 99 |
The basic design of Locale::Maketext is object-oriented, and |
| 100 |
Locale::Maketext is an abstract base class, from which you |
| 101 |
derive a "project class". |
| 102 |
The project class (with a name like "TkBocciBall::Localize", |
| 103 |
which you then use in your module) is in turn the base class |
| 104 |
for all the "language classes" for your project |
| 105 |
(with names "TkBocciBall::Localize::it", |
| 106 |
"TkBocciBall::Localize::en", |
| 107 |
"TkBocciBall::Localize::fr", etc.). |
| 108 |
.PP |
| 109 |
A language class is |
| 110 |
a class containing a lexicon of phrases as class data, |
| 111 |
and possibly also some methods that are of use in interpreting |
| 112 |
phrases in the lexicon, or otherwise dealing with text in that |
| 113 |
language. |
| 114 |
.PP |
| 115 |
An object belonging to a language class is called a "language |
| 116 |
handle"; it's typically a flyweight object. |
| 117 |
.PP |
| 118 |
The normal course of action is to call: |
| 119 |
.PP |
| 120 |
.Vb 6 |
| 121 |
\& use TkBocciBall::Localize; # the localization project class |
| 122 |
\& $lh = TkBocciBall::Localize\->get_handle(); |
| 123 |
\& # Depending on the user\*(Aqs locale, etc., this will |
| 124 |
\& # make a language handle from among the classes available, |
| 125 |
\& # and any defaults that you declare. |
| 126 |
\& die "Couldn\*(Aqt make a language handle??" unless $lh; |
| 127 |
.Ve |
| 128 |
.PP |
| 129 |
From then on, you use the \f(CW\*(C`maketext\*(C'\fR function to access |
| 130 |
entries in whatever lexicon(s) belong to the language handle |
| 131 |
you got. So, this: |
| 132 |
.PP |
| 133 |
.Vb 1 |
| 134 |
\& print $lh\->maketext("You won!"), "\en"; |
| 135 |
.Ve |
| 136 |
.PP |
| 137 |
\&...emits the right text for this language. If the object |
| 138 |
in \f(CW$lh\fR belongs to class "TkBocciBall::Localize::fr" and |
| 139 |
\&\f(CW%TkBocciBall::Localize::fr::Lexicon\fR contains \f(CW\*(C`("You won!" |
| 140 |
=> "Tu as gagné!")\*(C'\fR, then the above |
| 141 |
code happily tells the user "Tu as gagné!". |
| 142 |
.SH METHODS |
| 143 |
.IX Header "METHODS" |
| 144 |
Locale::Maketext offers a variety of methods, which fall |
| 145 |
into three categories: |
| 146 |
.IP \(bu 4 |
| 147 |
Methods to do with constructing language handles. |
| 148 |
.IP \(bu 4 |
| 149 |
\&\f(CW\*(C`maketext\*(C'\fR and other methods to do with accessing \f(CW%Lexicon\fR data |
| 150 |
for a given language handle. |
| 151 |
.IP \(bu 4 |
| 152 |
Methods that you may find it handy to use, from routines of |
| 153 |
yours that you put in \f(CW%Lexicon\fR entries. |
| 154 |
.PP |
| 155 |
These are covered in the following section. |
| 156 |
.SS "Construction Methods" |
| 157 |
.IX Subsection "Construction Methods" |
| 158 |
These are to do with constructing a language handle: |
| 159 |
.IP \(bu 4 |
| 160 |
\&\f(CW$lh\fR = YourProjClass\->get_handle( ...langtags... ) || die "lg-handle?"; |
| 161 |
.Sp |
| 162 |
This tries loading classes based on the language-tags you give (like |
| 163 |
\&\f(CW\*(C`("en\-US", "sk", "kon", "es\-MX", "ja", "i\-klingon")\*(C'\fR, and for the first class |
| 164 |
that succeeds, returns YourProjClass::\fIlanguage\fR\->\fBnew()\fR. |
| 165 |
.Sp |
| 166 |
If it runs thru the entire given list of language-tags, and finds no classes |
| 167 |
for those exact terms, it then tries "superordinate" language classes. |
| 168 |
So if no "en-US" class (i.e., YourProjClass::en_us) |
| 169 |
was found, nor classes for anything else in that list, we then try |
| 170 |
its superordinate, "en" (i.e., YourProjClass::en), and so on thru |
| 171 |
the other language-tags in the given list: "es". |
| 172 |
(The other language-tags in our example list: |
| 173 |
happen to have no superordinates.) |
| 174 |
.Sp |
| 175 |
If none of those language-tags leads to loadable classes, we then |
| 176 |
try classes derived from YourProjClass\->\fBfallback_languages()\fR and |
| 177 |
then if nothing comes of that, we use classes named by |
| 178 |
YourProjClass\->\fBfallback_language_classes()\fR. Then in the (probably |
| 179 |
quite unlikely) event that that fails, we just return undef. |
| 180 |
.IP \(bu 4 |
| 181 |
\&\f(CW$lh\fR = YourProjClass\->get_handle\fB()\fR || die "lg-handle?"; |
| 182 |
.Sp |
| 183 |
When \f(CW\*(C`get_handle\*(C'\fR is called with an empty parameter list, magic happens: |
| 184 |
.Sp |
| 185 |
If \f(CW\*(C`get_handle\*(C'\fR senses that it's running in program that was |
| 186 |
invoked as a CGI, then it tries to get language-tags out of the |
| 187 |
environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that |
| 188 |
those were the languages passed as parameters to \f(CW\*(C`get_handle\*(C'\fR. |
| 189 |
.Sp |
| 190 |
Otherwise (i.e., if not a CGI), this tries various OS-specific ways |
| 191 |
to get the language-tags for the current locale/language, and then |
| 192 |
pretends that those were the value(s) passed to \f(CW\*(C`get_handle\*(C'\fR. |
| 193 |
.Sp |
| 194 |
Currently this OS-specific stuff consists of looking in the environment |
| 195 |
variables "LANG" and "LANGUAGE"; and on MSWin machines (where those |
| 196 |
variables are typically unused), this also tries using |
| 197 |
the module Win32::Locale to get a language-tag for whatever language/locale |
| 198 |
is currently selected in the "Regional Settings" (or "International"?) |
| 199 |
Control Panel. I welcome further |
| 200 |
suggestions for making this do the Right Thing under other operating |
| 201 |
systems that support localization. |
| 202 |
.Sp |
| 203 |
If you're using localization in an application that keeps a configuration |
| 204 |
file, you might consider something like this in your project class: |
| 205 |
.Sp |
| 206 |
.Vb 10 |
| 207 |
\& sub get_handle_via_config { |
| 208 |
\& my $class = $_[0]; |
| 209 |
\& my $chosen_language = $Config_settings{\*(Aqlanguage\*(Aq}; |
| 210 |
\& my $lh; |
| 211 |
\& if($chosen_language) { |
| 212 |
\& $lh = $class\->get_handle($chosen_language) |
| 213 |
\& || die "No language handle for \e"$chosen_language\e"" |
| 214 |
\& . " or the like"; |
| 215 |
\& } else { |
| 216 |
\& # Config file missing, maybe? |
| 217 |
\& $lh = $class\->get_handle() |
| 218 |
\& || die "Can\*(Aqt get a language handle"; |
| 219 |
\& } |
| 220 |
\& return $lh; |
| 221 |
\& } |
| 222 |
.Ve |
| 223 |
.IP \(bu 4 |
| 224 |
\&\f(CW$lh\fR = YourProjClass::langname\->\fBnew()\fR; |
| 225 |
.Sp |
| 226 |
This constructs a language handle. You usually \fBdon't\fR call this |
| 227 |
directly, but instead let \f(CW\*(C`get_handle\*(C'\fR find a language class to \f(CW\*(C`use\*(C'\fR |
| 228 |
and to then call \->new on. |
| 229 |
.IP \(bu 4 |
| 230 |
\&\f(CW$lh\fR\->\fBinit()\fR; |
| 231 |
.Sp |
| 232 |
This is called by \->new to initialize newly-constructed language handles. |
| 233 |
If you define an init method in your class, remember that it's usually |
| 234 |
considered a good idea to call \f(CW$lh\fR\->SUPER::init in it (presumably at the |
| 235 |
beginning), so that all classes get a chance to initialize a new object |
| 236 |
however they see fit. |
| 237 |
.IP \(bu 4 |
| 238 |
YourProjClass\->\fBfallback_languages()\fR |
| 239 |
.Sp |
| 240 |
\&\f(CW\*(C`get_handle\*(C'\fR appends the return value of this to the end of |
| 241 |
whatever list of languages you pass \f(CW\*(C`get_handle\*(C'\fR. Unless |
| 242 |
you override this method, your project class |
| 243 |
will inherit Locale::Maketext's \f(CW\*(C`fallback_languages\*(C'\fR, which |
| 244 |
currently returns \f(CW\*(C`(\*(Aqi\-default\*(Aq, \*(Aqen\*(Aq, \*(Aqen\-US\*(Aq)\*(C'\fR. |
| 245 |
("i\-default" is defined in RFC 2277). |
| 246 |
.Sp |
| 247 |
This method (by having it return the name |
| 248 |
of a language-tag that has an existing language class) |
| 249 |
can be used for making sure that |
| 250 |
\&\f(CW\*(C`get_handle\*(C'\fR will always manage to construct a language |
| 251 |
handle (assuming your language classes are in an appropriate |
| 252 |
\&\f(CW@INC\fR directory). Or you can use the next method: |
| 253 |
.IP \(bu 4 |
| 254 |
YourProjClass\->\fBfallback_language_classes()\fR |
| 255 |
.Sp |
| 256 |
\&\f(CW\*(C`get_handle\*(C'\fR appends the return value of this to the end |
| 257 |
of the list of classes it will try using. Unless |
| 258 |
you override this method, your project class |
| 259 |
will inherit Locale::Maketext's \f(CW\*(C`fallback_language_classes\*(C'\fR, |
| 260 |
which currently returns an empty list, \f(CW\*(C`()\*(C'\fR. |
| 261 |
By setting this to some value (namely, the name of a loadable |
| 262 |
language class), you can be sure that |
| 263 |
\&\f(CW\*(C`get_handle\*(C'\fR will always manage to construct a language |
| 264 |
handle. |
| 265 |
.SS "The ""maketext"" Method" |
| 266 |
.IX Subsection "The ""maketext"" Method" |
| 267 |
This is the most important method in Locale::Maketext: |
| 268 |
.PP |
| 269 |
.Vb 1 |
| 270 |
\& $text = $lh\->maketext(I<key>, ...parameters for this phrase...); |
| 271 |
.Ve |
| 272 |
.PP |
| 273 |
This looks in the \f(CW%Lexicon\fR of the language handle |
| 274 |
\&\f(CW$lh\fR and all its superclasses, looking |
| 275 |
for an entry whose key is the string \fIkey\fR. Assuming such |
| 276 |
an entry is found, various things then happen, depending on the |
| 277 |
value found: |
| 278 |
.PP |
| 279 |
If the value is a scalarref, the scalar is dereferenced and returned |
| 280 |
(and any parameters are ignored). |
| 281 |
.PP |
| 282 |
If the value is a coderef, we return &$value($lh, ...parameters...). |
| 283 |
.PP |
| 284 |
If the value is a string that \fIdoesn't\fR look like it's in Bracket Notation, |
| 285 |
we return it (after replacing it with a scalarref, in its \f(CW%Lexicon\fR). |
| 286 |
.PP |
| 287 |
If the value \fIdoes\fR look like it's in Bracket Notation, then we compile |
| 288 |
it into a sub, replace the string in the \f(CW%Lexicon\fR with the new coderef, |
| 289 |
and then we return &$new_sub($lh, ...parameters...). |
| 290 |
.PP |
| 291 |
Bracket Notation is discussed in a later section. Note |
| 292 |
that trying to compile a string into Bracket Notation can throw |
| 293 |
an exception if the string is not syntactically valid (say, by not |
| 294 |
balancing brackets right.) |
| 295 |
.PP |
| 296 |
Also, calling &$coderef($lh, ...parameters...) can throw any sort of |
| 297 |
exception (if, say, code in that sub tries to divide by zero). But |
| 298 |
a very common exception occurs when you have Bracket |
| 299 |
Notation text that says to call a method "foo", but there is no such |
| 300 |
method. (E.g., "You have [qua\fBtn\fR,_1,ball]." will throw an exception |
| 301 |
on trying to call \f(CW$lh\fR\->qua\fBtn\fR($_[1],'ball') \-\- you presumably meant |
| 302 |
"quant".) \f(CW\*(C`maketext\*(C'\fR catches these exceptions, but only to make the |
| 303 |
error message more readable, at which point it rethrows the exception. |
| 304 |
.PP |
| 305 |
An exception \fImay\fR be thrown if \fIkey\fR is not found in any |
| 306 |
of \f(CW$lh\fR's \f(CW%Lexicon\fR hashes. What happens if a key is not found, |
| 307 |
is discussed in a later section, "Controlling Lookup Failure". |
| 308 |
.PP |
| 309 |
Note that you might find it useful in some cases to override |
| 310 |
the \f(CW\*(C`maketext\*(C'\fR method with an "after method", if you want to |
| 311 |
translate encodings, or even scripts: |
| 312 |
.PP |
| 313 |
.Vb 7 |
| 314 |
\& package YrProj::zh_cn; # Chinese with PRC\-style glyphs |
| 315 |
\& use base (\*(AqYrProj::zh_tw\*(Aq); # Taiwan\-style |
| 316 |
\& sub maketext { |
| 317 |
\& my $self = shift(@_); |
| 318 |
\& my $value = $self\->maketext(@_); |
| 319 |
\& return Chineeze::taiwan2mainland($value); |
| 320 |
\& } |
| 321 |
.Ve |
| 322 |
.PP |
| 323 |
Or you may want to override it with something that traps |
| 324 |
any exceptions, if that's critical to your program: |
| 325 |
.PP |
| 326 |
.Vb 7 |
| 327 |
\& sub maketext { |
| 328 |
\& my($lh, @stuff) = @_; |
| 329 |
\& my $out; |
| 330 |
\& eval { $out = $lh\->SUPER::maketext(@stuff) }; |
| 331 |
\& return $out unless $@; |
| 332 |
\& ...otherwise deal with the exception... |
| 333 |
\& } |
| 334 |
.Ve |
| 335 |
.PP |
| 336 |
Other than those two situations, I don't imagine that |
| 337 |
it's useful to override the \f(CW\*(C`maketext\*(C'\fR method. (If |
| 338 |
you run into a situation where it is useful, I'd be |
| 339 |
interested in hearing about it.) |
| 340 |
.ie n .IP "$lh\->fail_with \fIor\fR $lh\->fail_with(\fIPARAM\fR)" 4 |
| 341 |
.el .IP "\f(CW$lh\fR\->fail_with \fIor\fR \f(CW$lh\fR\->fail_with(\fIPARAM\fR)" 4 |
| 342 |
.IX Item "$lh->fail_with or $lh->fail_with(PARAM)" |
| 343 |
.PD 0 |
| 344 |
.ie n .IP $lh\->failure_handler_auto 4 |
| 345 |
.el .IP \f(CW$lh\fR\->failure_handler_auto 4 |
| 346 |
.IX Item "$lh->failure_handler_auto" |
| 347 |
.PD |
| 348 |
These two methods are discussed in the section "Controlling |
| 349 |
Lookup Failure". |
| 350 |
.ie n .IP "$lh\->denylist(@list) <or> $lh\->blacklist(@list)" 4 |
| 351 |
.el .IP "\f(CW$lh\fR\->denylist(@list) <or> \f(CW$lh\fR\->blacklist(@list)" 4 |
| 352 |
.IX Item "$lh->denylist(@list) <or> $lh->blacklist(@list)" |
| 353 |
.PD 0 |
| 354 |
.ie n .IP "$lh\->allowlist(@list) <or> $lh\->whitelist(@list)" 4 |
| 355 |
.el .IP "\f(CW$lh\fR\->allowlist(@list) <or> \f(CW$lh\fR\->whitelist(@list)" 4 |
| 356 |
.IX Item "$lh->allowlist(@list) <or> $lh->whitelist(@list)" |
| 357 |
.PD |
| 358 |
These methods are discussed in the section "Bracket Notation |
| 359 |
Security". |
| 360 |
.SS "Utility Methods" |
| 361 |
.IX Subsection "Utility Methods" |
| 362 |
These are methods that you may find it handy to use, generally |
| 363 |
from \f(CW%Lexicon\fR routines of yours (whether expressed as |
| 364 |
Bracket Notation or not). |
| 365 |
.ie n .IP "$language\->quant($number, $singular)" 4 |
| 366 |
.el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR)" 4 |
| 367 |
.IX Item "$language->quant($number, $singular)" |
| 368 |
.PD 0 |
| 369 |
.ie n .IP "$language\->quant($number, $singular, $plural)" 4 |
| 370 |
.el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural\fR)" 4 |
| 371 |
.IX Item "$language->quant($number, $singular, $plural)" |
| 372 |
.ie n .IP "$language\->quant($number, $singular, $plural, $negative)" 4 |
| 373 |
.el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural\fR, \f(CW$negative\fR)" 4 |
| 374 |
.IX Item "$language->quant($number, $singular, $plural, $negative)" |
| 375 |
.PD |
| 376 |
This is generally meant to be called from inside Bracket Notation |
| 377 |
(which is discussed later), as in |
| 378 |
.Sp |
| 379 |
.Vb 1 |
| 380 |
\& "Your search matched [quant,_1,document]!" |
| 381 |
.Ve |
| 382 |
.Sp |
| 383 |
It's for \fIquantifying\fR a noun (i.e., saying how much of it there is, |
| 384 |
while giving the correct form of it). The behavior of this method is |
| 385 |
handy for English and a few other Western European languages, and you |
| 386 |
should override it for languages where it's not suitable. You can feel |
| 387 |
free to read the source, but the current implementation is basically |
| 388 |
as this pseudocode describes: |
| 389 |
.Sp |
| 390 |
.Vb 11 |
| 391 |
\& if $number is 0 and there\*(Aqs a $negative, |
| 392 |
\& return $negative; |
| 393 |
\& elsif $number is 1, |
| 394 |
\& return "1 $singular"; |
| 395 |
\& elsif there\*(Aqs a $plural, |
| 396 |
\& return "$number $plural"; |
| 397 |
\& else |
| 398 |
\& return "$number " . $singular . "s"; |
| 399 |
\& # |
| 400 |
\& # ...except that we actually call numf to |
| 401 |
\& # stringify $number before returning it. |
| 402 |
.Ve |
| 403 |
.Sp |
| 404 |
So for English (with Bracket Notation) |
| 405 |
\&\f(CW"...[quant,_1,file]..."\fR is fine (for 0 it returns "0 files", |
| 406 |
for 1 it returns "1 file", and for more it returns "2 files", etc.) |
| 407 |
.Sp |
| 408 |
But for "directory", you'd want \f(CW"[quant,_1,directory,directories]"\fR |
| 409 |
so that our elementary \f(CW\*(C`quant\*(C'\fR method doesn't think that the |
| 410 |
plural of "directory" is "directorys". And you might find that the |
| 411 |
output may sound better if you specify a negative form, as in: |
| 412 |
.Sp |
| 413 |
.Vb 1 |
| 414 |
\& "[quant,_1,file,files,No files] matched your query.\en" |
| 415 |
.Ve |
| 416 |
.Sp |
| 417 |
Remember to keep in mind verb agreement (or adjectives too, in |
| 418 |
other languages), as in: |
| 419 |
.Sp |
| 420 |
.Vb 1 |
| 421 |
\& "[quant,_1,document] were matched.\en" |
| 422 |
.Ve |
| 423 |
.Sp |
| 424 |
Because if _1 is one, you get "1 document \fBwere\fR matched". |
| 425 |
An acceptable hack here is to do something like this: |
| 426 |
.Sp |
| 427 |
.Vb 1 |
| 428 |
\& "[quant,_1,document was, documents were] matched.\en" |
| 429 |
.Ve |
| 430 |
.ie n .IP $language\->numf($number) 4 |
| 431 |
.el .IP \f(CW$language\fR\->numf($number) 4 |
| 432 |
.IX Item "$language->numf($number)" |
| 433 |
This returns the given number formatted nicely according to |
| 434 |
this language's conventions. Maketext's default method is |
| 435 |
mostly to just take the normal string form of the number |
| 436 |
(applying sprintf "%G" for only very large numbers), and then |
| 437 |
to add commas as necessary. (Except that |
| 438 |
we apply \f(CW\*(C`tr/,./.,/\*(C'\fR if \f(CW$language\fR\->{'numf_comma'} is true; |
| 439 |
that's a bit of a hack that's useful for languages that express |
| 440 |
two million as "2.000.000" and not as "2,000,000"). |
| 441 |
.Sp |
| 442 |
If you want anything fancier, consider overriding this with something |
| 443 |
that uses Number::Format, or does something else |
| 444 |
entirely. |
| 445 |
.Sp |
| 446 |
Note that numf is called by quant for stringifying all quantifying |
| 447 |
numbers. |
| 448 |
.ie n .IP "$language\->numerate($number, $singular, $plural, $negative)" 4 |
| 449 |
.el .IP "\f(CW$language\fR\->numerate($number, \f(CW$singular\fR, \f(CW$plural\fR, \f(CW$negative\fR)" 4 |
| 450 |
.IX Item "$language->numerate($number, $singular, $plural, $negative)" |
| 451 |
This returns the given noun form which is appropriate for the quantity |
| 452 |
\&\f(CW$number\fR according to this language's conventions. \f(CW\*(C`numerate\*(C'\fR is |
| 453 |
used internally by \f(CW\*(C`quant\*(C'\fR to quantify nouns. Use it directly \-\- |
| 454 |
usually from bracket notation \-\- to avoid \f(CW\*(C`quant\*(C'\fR's implicit call to |
| 455 |
\&\f(CW\*(C`numf\*(C'\fR and output of a numeric quantity. |
| 456 |
.ie n .IP "$language\->sprintf($format, @items)" 4 |
| 457 |
.el .IP "\f(CW$language\fR\->sprintf($format, \f(CW@items\fR)" 4 |
| 458 |
.IX Item "$language->sprintf($format, @items)" |
| 459 |
This is just a wrapper around Perl's normal \f(CW\*(C`sprintf\*(C'\fR function. |
| 460 |
It's provided so that you can use "sprintf" in Bracket Notation: |
| 461 |
.Sp |
| 462 |
.Vb 1 |
| 463 |
\& "Couldn\*(Aqt access datanode [sprintf,%10x=~[%s~],_1,_2]!\en" |
| 464 |
.Ve |
| 465 |
.Sp |
| 466 |
returning... |
| 467 |
.Sp |
| 468 |
.Vb 1 |
| 469 |
\& Couldn\*(Aqt access datanode Stuff=[thangamabob]! |
| 470 |
.Ve |
| 471 |
.ie n .IP $language\->\fBlanguage_tag()\fR 4 |
| 472 |
.el .IP \f(CW$language\fR\->\fBlanguage_tag()\fR 4 |
| 473 |
.IX Item "$language->language_tag()" |
| 474 |
Currently this just takes the last bit of \f(CWref($language)\fR, turns |
| 475 |
underscores to dashes, and returns it. So if \f(CW$language\fR is |
| 476 |
an object of class Hee::HOO::Haw::en_us, \f(CW$language\fR\->\fBlanguage_tag()\fR |
| 477 |
returns "en-us". (Yes, the usual representation for that language |
| 478 |
tag is "en-US", but case is \fInever\fR considered meaningful in |
| 479 |
language-tag comparison.) |
| 480 |
.Sp |
| 481 |
You may override this as you like; Maketext doesn't use it for |
| 482 |
anything. |
| 483 |
.ie n .IP $language\->\fBencoding()\fR 4 |
| 484 |
.el .IP \f(CW$language\fR\->\fBencoding()\fR 4 |
| 485 |
.IX Item "$language->encoding()" |
| 486 |
Currently this isn't used for anything, but it's provided |
| 487 |
(with default value of |
| 488 |
\&\f(CW\*(C`(ref($language) && $language\->{\*(Aqencoding\*(Aq})) or "iso\-8859\-1"\*(C'\fR |
| 489 |
) as a sort of suggestion that it may be useful/necessary to |
| 490 |
associate encodings with your language handles (whether on a |
| 491 |
per-class or even per-handle basis.) |
| 492 |
.SS "Language Handle Attributes and Internals" |
| 493 |
.IX Subsection "Language Handle Attributes and Internals" |
| 494 |
A language handle is a flyweight object \-\- i.e., it doesn't (necessarily) |
| 495 |
carry any data of interest, other than just being a member of |
| 496 |
whatever class it belongs to. |
| 497 |
.PP |
| 498 |
A language handle is implemented as a blessed hash. Subclasses of yours |
| 499 |
can store whatever data you want in the hash. Currently the only hash |
| 500 |
entry used by any crucial Maketext method is "fail", so feel free to |
| 501 |
use anything else as you like. |
| 502 |
.PP |
| 503 |
\&\fBRemember: Don't be afraid to read the Maketext source if there's |
| 504 |
any point on which this documentation is unclear.\fR This documentation |
| 505 |
is vastly longer than the module source itself. |
| 506 |
.SH "LANGUAGE CLASS HIERARCHIES" |
| 507 |
.IX Header "LANGUAGE CLASS HIERARCHIES" |
| 508 |
These are Locale::Maketext's assumptions about the class |
| 509 |
hierarchy formed by all your language classes: |
| 510 |
.IP \(bu 4 |
| 511 |
You must have a project base class, which you load, and |
| 512 |
which you then use as the first argument in |
| 513 |
the call to YourProjClass\->get_handle(...). It should derive |
| 514 |
(whether directly or indirectly) from Locale::Maketext. |
| 515 |
It \fBdoesn't matter\fR how you name this class, although assuming this |
| 516 |
is the localization component of your Super Mega Program, |
| 517 |
good names for your project class might be |
| 518 |
SuperMegaProgram::Localization, SuperMegaProgram::L10N, |
| 519 |
SuperMegaProgram::I18N, SuperMegaProgram::International, |
| 520 |
or even SuperMegaProgram::Languages or SuperMegaProgram::Messages. |
| 521 |
.IP \(bu 4 |
| 522 |
Language classes are what YourProjClass\->get_handle will try to load. |
| 523 |
It will look for them by taking each language-tag (\fBskipping\fR it |
| 524 |
if it doesn't look like a language-tag or locale-tag!), turning it to |
| 525 |
all lowercase, turning dashes to underscores, and appending it |
| 526 |
to YourProjClass . "::". So this: |
| 527 |
.Sp |
| 528 |
.Vb 3 |
| 529 |
\& $lh = YourProjClass\->get_handle( |
| 530 |
\& \*(Aqen\-US\*(Aq, \*(Aqfr\*(Aq, \*(Aqkon\*(Aq, \*(Aqi\-klingon\*(Aq, \*(Aqi\-klingon\-romanized\*(Aq |
| 531 |
\& ); |
| 532 |
.Ve |
| 533 |
.Sp |
| 534 |
will try loading the classes |
| 535 |
YourProjClass::en_us (note lowercase!), YourProjClass::fr, |
| 536 |
YourProjClass::kon, |
| 537 |
YourProjClass::i_klingon |
| 538 |
and YourProjClass::i_klingon_romanized. (And it'll stop at the |
| 539 |
first one that actually loads.) |
| 540 |
.IP \(bu 4 |
| 541 |
I assume that each language class derives (directly or indirectly) |
| 542 |
from your project class, and also defines its \f(CW@ISA\fR, its \f(CW%Lexicon\fR, |
| 543 |
or both. But I anticipate no dire consequences if these assumptions |
| 544 |
do not hold. |
| 545 |
.IP \(bu 4 |
| 546 |
Language classes may derive from other language classes (although they |
| 547 |
should have "use \fIThatclassname\fR" or "use base qw(\fI...classes...\fR)"). |
| 548 |
They may derive from the project |
| 549 |
class. They may derive from some other class altogether. Or via |
| 550 |
multiple inheritance, it may derive from any mixture of these. |
| 551 |
.IP \(bu 4 |
| 552 |
I foresee no problems with having multiple inheritance in |
| 553 |
your hierarchy of language classes. (As usual, however, Perl will |
| 554 |
complain bitterly if you have a cycle in the hierarchy: i.e., if |
| 555 |
any class is its own ancestor.) |
| 556 |
.SH "ENTRIES IN EACH LEXICON" |
| 557 |
.IX Header "ENTRIES IN EACH LEXICON" |
| 558 |
A typical \f(CW%Lexicon\fR entry is meant to signify a phrase, |
| 559 |
taking some number (0 or more) of parameters. An entry |
| 560 |
is meant to be accessed by via |
| 561 |
a string \fIkey\fR in \f(CW$lh\fR\->maketext(\fIkey\fR, ...parameters...), |
| 562 |
which should return a string that is generally meant for |
| 563 |
be used for "output" to the user \-\- regardless of whether |
| 564 |
this actually means printing to STDOUT, writing to a file, |
| 565 |
or putting into a GUI widget. |
| 566 |
.PP |
| 567 |
While the key must be a string value (since that's a basic |
| 568 |
restriction that Perl places on hash keys), the value in |
| 569 |
the lexicon can currently be of several types: |
| 570 |
a defined scalar, scalarref, or coderef. The use of these is |
| 571 |
explained above, in the section 'The "maketext" Method', and |
| 572 |
Bracket Notation for strings is discussed in the next section. |
| 573 |
.PP |
| 574 |
While you can use arbitrary unique IDs for lexicon keys |
| 575 |
(like "_min_larger_max_error"), it is often |
| 576 |
useful for if an entry's key is itself a valid value, like |
| 577 |
this example error message: |
| 578 |
.PP |
| 579 |
.Vb 1 |
| 580 |
\& "Minimum ([_1]) is larger than maximum ([_2])!\en", |
| 581 |
.Ve |
| 582 |
.PP |
| 583 |
Compare this code that uses an arbitrary ID... |
| 584 |
.PP |
| 585 |
.Vb 2 |
| 586 |
\& die $lh\->maketext( "_min_larger_max_error", $min, $max ) |
| 587 |
\& if $min > $max; |
| 588 |
.Ve |
| 589 |
.PP |
| 590 |
\&...to this code that uses a key-as-value: |
| 591 |
.PP |
| 592 |
.Vb 4 |
| 593 |
\& die $lh\->maketext( |
| 594 |
\& "Minimum ([_1]) is larger than maximum ([_2])!\en", |
| 595 |
\& $min, $max |
| 596 |
\& ) if $min > $max; |
| 597 |
.Ve |
| 598 |
.PP |
| 599 |
The second is, in short, more readable. In particular, it's obvious |
| 600 |
that the number of parameters you're feeding to that phrase (two) is |
| 601 |
the number of parameters that it \fIwants\fR to be fed. (Since you see |
| 602 |
_1 and a _2 being used in the key there.) |
| 603 |
.PP |
| 604 |
Also, once a project is otherwise |
| 605 |
complete and you start to localize it, you can scrape together |
| 606 |
all the various keys you use, and pass it to a translator; and then |
| 607 |
the translator's work will go faster if what he's presented is this: |
| 608 |
.PP |
| 609 |
.Vb 2 |
| 610 |
\& "Minimum ([_1]) is larger than maximum ([_2])!\en", |
| 611 |
\& => "", # fill in something here, Jacques! |
| 612 |
.Ve |
| 613 |
.PP |
| 614 |
rather than this more cryptic mess: |
| 615 |
.PP |
| 616 |
.Vb 2 |
| 617 |
\& "_min_larger_max_error" |
| 618 |
\& => "", # fill in something here, Jacques |
| 619 |
.Ve |
| 620 |
.PP |
| 621 |
I think that keys as lexicon values makes the completed lexicon |
| 622 |
entries more readable: |
| 623 |
.PP |
| 624 |
.Vb 2 |
| 625 |
\& "Minimum ([_1]) is larger than maximum ([_2])!\en", |
| 626 |
\& => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\en", |
| 627 |
.Ve |
| 628 |
.PP |
| 629 |
Also, having valid values as keys becomes very useful if you set |
| 630 |
up an _AUTO lexicon. _AUTO lexicons are discussed in a later |
| 631 |
section. |
| 632 |
.PP |
| 633 |
I almost always use keys that are themselves |
| 634 |
valid lexicon values. One notable exception is when the value is |
| 635 |
quite long. For example, to get the screenful of data that |
| 636 |
a command-line program might return when given an unknown switch, |
| 637 |
I often just use a brief, self-explanatory key such as "_USAGE_MESSAGE". At that point I then go |
| 638 |
and immediately to define that lexicon entry in the |
| 639 |
ProjectClass::L10N::en lexicon (since English is always my "project |
| 640 |
language"): |
| 641 |
.PP |
| 642 |
.Vb 3 |
| 643 |
\& \*(Aq_USAGE_MESSAGE\*(Aq => <<\*(AqEOSTUFF\*(Aq, |
| 644 |
\& ...long long message... |
| 645 |
\& EOSTUFF |
| 646 |
.Ve |
| 647 |
.PP |
| 648 |
and then I can use it as: |
| 649 |
.PP |
| 650 |
.Vb 1 |
| 651 |
\& getopt(\*(AqoDI\*(Aq, \e%opts) or die $lh\->maketext(\*(Aq_USAGE_MESSAGE\*(Aq); |
| 652 |
.Ve |
| 653 |
.PP |
| 654 |
Incidentally, |
| 655 |
note that each class's \f(CW%Lexicon\fR inherits-and-extends |
| 656 |
the lexicons in its superclasses. This is not because these are |
| 657 |
special hashes \fIper se\fR, but because you access them via the |
| 658 |
\&\f(CW\*(C`maketext\*(C'\fR method, which looks for entries across all the |
| 659 |
\&\f(CW%Lexicon\fR hashes in a language class \fIand\fR all its ancestor classes. |
| 660 |
(This is because the idea of "class data" isn't directly implemented |
| 661 |
in Perl, but is instead left to individual class-systems to implement |
| 662 |
as they see fit..) |
| 663 |
.PP |
| 664 |
Note that you may have things stored in a lexicon |
| 665 |
besides just phrases for output: for example, if your program |
| 666 |
takes input from the keyboard, asking a "(Y/N)" question, |
| 667 |
you probably need to know what the equivalent of "Y[es]/N[o]" is |
| 668 |
in whatever language. You probably also need to know what |
| 669 |
the equivalents of the answers "y" and "n" are. You can |
| 670 |
store that information in the lexicon (say, under the keys |
| 671 |
"~answer_y" and "~answer_n", and the long forms as |
| 672 |
"~answer_yes" and "~answer_no", where "~" is just an ad-hoc |
| 673 |
character meant to indicate to programmers/translators that |
| 674 |
these are not phrases for output). |
| 675 |
.PP |
| 676 |
Or instead of storing this in the language class's lexicon, |
| 677 |
you can (and, in some cases, really should) represent the same bit |
| 678 |
of knowledge as code in a method in the language class. (That |
| 679 |
leaves a tidy distinction between the lexicon as the things we |
| 680 |
know how to \fIsay\fR, and the rest of the things in the lexicon class |
| 681 |
as things that we know how to \fIdo\fR.) Consider |
| 682 |
this example of a processor for responses to French "oui/non" |
| 683 |
questions: |
| 684 |
.PP |
| 685 |
.Vb 7 |
| 686 |
\& sub y_or_n { |
| 687 |
\& return undef unless defined $_[1] and length $_[1]; |
| 688 |
\& my $answer = lc $_[1]; # smash case |
| 689 |
\& return 1 if $answer eq \*(Aqo\*(Aq or $answer eq \*(Aqoui\*(Aq; |
| 690 |
\& return 0 if $answer eq \*(Aqn\*(Aq or $answer eq \*(Aqnon\*(Aq; |
| 691 |
\& return undef; |
| 692 |
\& } |
| 693 |
.Ve |
| 694 |
.PP |
| 695 |
\&...which you'd then call in a construct like this: |
| 696 |
.PP |
| 697 |
.Vb 7 |
| 698 |
\& my $response; |
| 699 |
\& until(defined $response) { |
| 700 |
\& print $lh\->maketext("Open the pod bay door (y/n)? "); |
| 701 |
\& $response = $lh\->y_or_n( get_input_from_keyboard_somehow() ); |
| 702 |
\& } |
| 703 |
\& if($response) { $pod_bay_door\->open() } |
| 704 |
\& else { $pod_bay_door\->leave_closed() } |
| 705 |
.Ve |
| 706 |
.PP |
| 707 |
Other data worth storing in a lexicon might be things like |
| 708 |
filenames for language-targetted resources: |
| 709 |
.PP |
| 710 |
.Vb 10 |
| 711 |
\& ... |
| 712 |
\& "_main_splash_png" |
| 713 |
\& => "/styles/en_us/main_splash.png", |
| 714 |
\& "_main_splash_imagemap" |
| 715 |
\& => "/styles/en_us/main_splash.incl", |
| 716 |
\& "_general_graphics_path" |
| 717 |
\& => "/styles/en_us/", |
| 718 |
\& "_alert_sound" |
| 719 |
\& => "/styles/en_us/hey_there.wav", |
| 720 |
\& "_forward_icon" |
| 721 |
\& => "left_arrow.png", |
| 722 |
\& "_backward_icon" |
| 723 |
\& => "right_arrow.png", |
| 724 |
\& # In some other languages, left equals |
| 725 |
\& # BACKwards, and right is FOREwards. |
| 726 |
\& ... |
| 727 |
.Ve |
| 728 |
.PP |
| 729 |
You might want to do the same thing for expressing key bindings |
| 730 |
or the like (since hardwiring "q" as the binding for the function |
| 731 |
that quits a screen/menu/program is useful only if your language |
| 732 |
happens to associate "q" with "quit"!) |
| 733 |
.SH "BRACKET NOTATION" |
| 734 |
.IX Header "BRACKET NOTATION" |
| 735 |
Bracket Notation is a crucial feature of Locale::Maketext. I mean |
| 736 |
Bracket Notation to provide a replacement for the use of sprintf formatting. |
| 737 |
Everything you do with Bracket Notation could be done with a sub block, |
| 738 |
but bracket notation is meant to be much more concise. |
| 739 |
.PP |
| 740 |
Bracket Notation is a like a miniature "template" system (in the sense |
| 741 |
of Text::Template, not in the sense of C++ templates), |
| 742 |
where normal text is passed thru basically as is, but text in special |
| 743 |
regions is specially interpreted. In Bracket Notation, you use square brackets ("[...]"), |
| 744 |
not curly braces ("{...}") to note sections that are specially interpreted. |
| 745 |
.PP |
| 746 |
For example, here all the areas that are taken literally are underlined with |
| 747 |
a "^", and all the in-bracket special regions are underlined with an X: |
| 748 |
.PP |
| 749 |
.Vb 2 |
| 750 |
\& "Minimum ([_1]) is larger than maximum ([_2])!\en", |
| 751 |
\& ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^ |
| 752 |
.Ve |
| 753 |
.PP |
| 754 |
When that string is compiled from bracket notation into a real Perl sub, |
| 755 |
it's basically turned into: |
| 756 |
.PP |
| 757 |
.Vb 11 |
| 758 |
\& sub { |
| 759 |
\& my $lh = $_[0]; |
| 760 |
\& my @params = @_; |
| 761 |
\& return join \*(Aq\*(Aq, |
| 762 |
\& "Minimum (", |
| 763 |
\& ...some code here... |
| 764 |
\& ") is larger than maximum (", |
| 765 |
\& ...some code here... |
| 766 |
\& ")!\en", |
| 767 |
\& } |
| 768 |
\& # to be called by $lh\->maketext(KEY, params...) |
| 769 |
.Ve |
| 770 |
.PP |
| 771 |
In other words, text outside bracket groups is turned into string |
| 772 |
literals. Text in brackets is rather more complex, and currently follows |
| 773 |
these rules: |
| 774 |
.IP \(bu 4 |
| 775 |
Bracket groups that are empty, or which consist only of whitespace, |
| 776 |
are ignored. (Examples: "[]", "[ ]", or a [ and a ] with returns |
| 777 |
and/or tabs and/or spaces between them. |
| 778 |
.Sp |
| 779 |
Otherwise, each group is taken to be a comma-separated group of items, |
| 780 |
and each item is interpreted as follows: |
| 781 |
.IP \(bu 4 |
| 782 |
An item that is "_\fIdigits\fR" or "_\-\fIdigits\fR" is interpreted as |
| 783 |
\&\f(CW$_\fR[\fIvalue\fR]. I.e., "_1" becomes with \f(CW$_\fR[1], and "_\-3" is interpreted |
| 784 |
as \f(CW$_\fR[\-3] (in which case \f(CW@_\fR should have at least three elements in it). |
| 785 |
Note that \f(CW$_\fR[0] is the language handle, and is typically not named |
| 786 |
directly. |
| 787 |
.IP \(bu 4 |
| 788 |
An item "_*" is interpreted to mean "all of \f(CW@_\fR except \f(CW$_\fR[0]". |
| 789 |
I.e., \f(CW@_[1..$#_]\fR. Note that this is an empty list in the case |
| 790 |
of calls like \f(CW$lh\fR\->maketext(\fIkey\fR) where there are no |
| 791 |
parameters (except \f(CW$_\fR[0], the language handle). |
| 792 |
.IP \(bu 4 |
| 793 |
Otherwise, each item is interpreted as a string literal. |
| 794 |
.PP |
| 795 |
The group as a whole is interpreted as follows: |
| 796 |
.IP \(bu 4 |
| 797 |
If the first item in a bracket group looks like a method name, |
| 798 |
then that group is interpreted like this: |
| 799 |
.Sp |
| 800 |
.Vb 3 |
| 801 |
\& $lh\->that_method_name( |
| 802 |
\& ...rest of items in this group... |
| 803 |
\& ), |
| 804 |
.Ve |
| 805 |
.IP \(bu 4 |
| 806 |
If the first item in a bracket group is "*", it's taken as shorthand |
| 807 |
for the so commonly called "quant" method. Similarly, if the first |
| 808 |
item in a bracket group is "#", it's taken to be shorthand for |
| 809 |
"numf". |
| 810 |
.IP \(bu 4 |
| 811 |
If the first item in a bracket group is the empty-string, or "_*" |
| 812 |
or "_\fIdigits\fR" or "_\-\fIdigits\fR", then that group is interpreted |
| 813 |
as just the interpolation of all its items: |
| 814 |
.Sp |
| 815 |
.Vb 3 |
| 816 |
\& join(\*(Aq\*(Aq, |
| 817 |
\& ...rest of items in this group... |
| 818 |
\& ), |
| 819 |
.Ve |
| 820 |
.Sp |
| 821 |
Examples: "[_1]" and "[,_1]", which are synonymous; and |
| 822 |
"\f(CW\*(C`[,ID\-(,_4,\-,_2,)]\*(C'\fR", which compiles as |
| 823 |
\&\f(CW\*(C`join "", "ID\-(", $_[4], "\-", $_[2], ")"\*(C'\fR. |
| 824 |
.IP \(bu 4 |
| 825 |
Otherwise this bracket group is invalid. For example, in the group |
| 826 |
"[!@#,whatever]", the first item \f(CW"!@#"\fR is neither the empty-string, |
| 827 |
"_\fInumber\fR", "_\-\fInumber\fR", "_*", nor a valid method name; and so |
| 828 |
Locale::Maketext will throw an exception of you try compiling an |
| 829 |
expression containing this bracket group. |
| 830 |
.PP |
| 831 |
Note, incidentally, that items in each group are comma-separated, |
| 832 |
not \f(CW\*(C`/\es*,\es*/\*(C'\fR\-separated. That is, you might expect that this |
| 833 |
bracket group: |
| 834 |
.PP |
| 835 |
.Vb 1 |
| 836 |
\& "Hoohah [foo, _1 , bar ,baz]!" |
| 837 |
.Ve |
| 838 |
.PP |
| 839 |
would compile to this: |
| 840 |
.PP |
| 841 |
.Vb 7 |
| 842 |
\& sub { |
| 843 |
\& my $lh = $_[0]; |
| 844 |
\& return join \*(Aq\*(Aq, |
| 845 |
\& "Hoohah ", |
| 846 |
\& $lh\->foo( $_[1], "bar", "baz"), |
| 847 |
\& "!", |
| 848 |
\& } |
| 849 |
.Ve |
| 850 |
.PP |
| 851 |
But it actually compiles as this: |
| 852 |
.PP |
| 853 |
.Vb 7 |
| 854 |
\& sub { |
| 855 |
\& my $lh = $_[0]; |
| 856 |
\& return join \*(Aq\*(Aq, |
| 857 |
\& "Hoohah ", |
| 858 |
\& $lh\->foo(" _1 ", " bar ", "baz"), # note the <space> in " bar " |
| 859 |
\& "!", |
| 860 |
\& } |
| 861 |
.Ve |
| 862 |
.PP |
| 863 |
In the notation discussed so far, the characters "[" and "]" are given |
| 864 |
special meaning, for opening and closing bracket groups, and "," has |
| 865 |
a special meaning inside bracket groups, where it separates items in the |
| 866 |
group. This begs the question of how you'd express a literal "[" or |
| 867 |
"]" in a Bracket Notation string, and how you'd express a literal |
| 868 |
comma inside a bracket group. For this purpose I've adopted "~" (tilde) |
| 869 |
as an escape character: "~[" means a literal '[' character anywhere |
| 870 |
in Bracket Notation (i.e., regardless of whether you're in a bracket |
| 871 |
group or not), and ditto for "~]" meaning a literal ']', and "~," meaning |
| 872 |
a literal comma. (Altho "," means a literal comma outside of |
| 873 |
bracket groups \-\- it's only inside bracket groups that commas are special.) |
| 874 |
.PP |
| 875 |
And on the off chance you need a literal tilde in a bracket expression, |
| 876 |
you get it with "~~". |
| 877 |
.PP |
| 878 |
Currently, an unescaped "~" before a character |
| 879 |
other than a bracket or a comma is taken to mean just a "~" and that |
| 880 |
character. I.e., "~X" means the same as "~~X" \-\- i.e., one literal tilde, |
| 881 |
and then one literal "X". However, by using "~X", you are assuming that |
| 882 |
no future version of Maketext will use "~X" as a magic escape sequence. |
| 883 |
In practice this is not a great problem, since first off you can just |
| 884 |
write "~~X" and not worry about it; second off, I doubt I'll add lots |
| 885 |
of new magic characters to bracket notation; and third off, you |
| 886 |
aren't likely to want literal "~" characters in your messages anyway, |
| 887 |
since it's not a character with wide use in natural language text. |
| 888 |
.PP |
| 889 |
Brackets must be balanced \-\- every openbracket must have |
| 890 |
one matching closebracket, and vice versa. So these are all \fBinvalid\fR: |
| 891 |
.PP |
| 892 |
.Vb 4 |
| 893 |
\& "I ate [quant,_1,rhubarb pie." |
| 894 |
\& "I ate [quant,_1,rhubarb pie[." |
| 895 |
\& "I ate quant,_1,rhubarb pie]." |
| 896 |
\& "I ate quant,_1,rhubarb pie[." |
| 897 |
.Ve |
| 898 |
.PP |
| 899 |
Currently, bracket groups do not nest. That is, you \fBcannot\fR say: |
| 900 |
.PP |
| 901 |
.Vb 1 |
| 902 |
\& "Foo [bar,baz,[quux,quuux]]\en"; |
| 903 |
.Ve |
| 904 |
.PP |
| 905 |
If you need a notation that's that powerful, use normal Perl: |
| 906 |
.PP |
| 907 |
.Vb 11 |
| 908 |
\& %Lexicon = ( |
| 909 |
\& ... |
| 910 |
\& "some_key" => sub { |
| 911 |
\& my $lh = $_[0]; |
| 912 |
\& join \*(Aq\*(Aq, |
| 913 |
\& "Foo ", |
| 914 |
\& $lh\->bar(\*(Aqbaz\*(Aq, $lh\->quux(\*(Aqquuux\*(Aq)), |
| 915 |
\& "\en", |
| 916 |
\& }, |
| 917 |
\& ... |
| 918 |
\& ); |
| 919 |
.Ve |
| 920 |
.PP |
| 921 |
Or write the "bar" method so you don't need to pass it the |
| 922 |
output from calling quux. |
| 923 |
.PP |
| 924 |
I do not anticipate that you will need (or particularly want) |
| 925 |
to nest bracket groups, but you are welcome to email me with |
| 926 |
convincing (real-life) arguments to the contrary. |
| 927 |
.SH "BRACKET NOTATION SECURITY" |
| 928 |
.IX Header "BRACKET NOTATION SECURITY" |
| 929 |
Locale::Maketext does not use any special syntax to differentiate |
| 930 |
bracket notation methods from normal class or object methods. This |
| 931 |
design makes it vulnerable to format string attacks whenever it is |
| 932 |
used to process strings provided by untrusted users. |
| 933 |
.PP |
| 934 |
Locale::Maketext does support denylist and allowlist functionality |
| 935 |
to limit which methods may be called as bracket notation methods. |
| 936 |
.PP |
| 937 |
By default, Locale::Maketext denies all methods in the |
| 938 |
Locale::Maketext namespace that begin with the '_' character, |
| 939 |
and all methods which include Perl's namespace separator characters. |
| 940 |
.PP |
| 941 |
The default denylist for Locale::Maketext also prevents use of the |
| 942 |
following methods in bracket notation: |
| 943 |
.PP |
| 944 |
.Vb 10 |
| 945 |
\& denylist |
| 946 |
\& encoding |
| 947 |
\& fail_with |
| 948 |
\& failure_handler_auto |
| 949 |
\& fallback_language_classes |
| 950 |
\& fallback_languages |
| 951 |
\& get_handle |
| 952 |
\& init |
| 953 |
\& language_tag |
| 954 |
\& maketext |
| 955 |
\& new |
| 956 |
\& allowlist |
| 957 |
\& whitelist |
| 958 |
\& blacklist |
| 959 |
.Ve |
| 960 |
.PP |
| 961 |
This list can be extended by either deny-listing additional "known bad" |
| 962 |
methods, or allow-listing only "known good" methods. |
| 963 |
.PP |
| 964 |
To prevent specific methods from being called in bracket notation, use |
| 965 |
the \fBdenylist()\fR method: |
| 966 |
.PP |
| 967 |
.Vb 3 |
| 968 |
\& my $lh = MyProgram::L10N\->get_handle(); |
| 969 |
\& $lh\->denylist(qw{my_internal_method my_other_method}); |
| 970 |
\& $lh\->maketext(\*(Aq[my_internal_method]\*(Aq); # dies |
| 971 |
.Ve |
| 972 |
.PP |
| 973 |
To limit the allowed bracked notation methods to a specific list, use the |
| 974 |
\&\fBallowlist()\fR method: |
| 975 |
.PP |
| 976 |
.Vb 4 |
| 977 |
\& my $lh = MyProgram::L10N\->get_handle(); |
| 978 |
\& $lh\->allowlist(\*(Aqnumerate\*(Aq, \*(Aqnumf\*(Aq); |
| 979 |
\& $lh\->maketext(\*(Aq[_1] [numerate, _1,shoe,shoes]\*(Aq, 12); # works |
| 980 |
\& $lh\->maketext(\*(Aq[my_internal_method]\*(Aq); # dies |
| 981 |
.Ve |
| 982 |
.PP |
| 983 |
The \fBdenylist()\fR and \fBallowlist()\fR methods extend their internal lists |
| 984 |
whenever they are called. To reset the denylist or allowlist, create |
| 985 |
a new maketext object. |
| 986 |
.PP |
| 987 |
.Vb 4 |
| 988 |
\& my $lh = MyProgram::L10N\->get_handle(); |
| 989 |
\& $lh\->denylist(\*(Aqnumerate\*(Aq); |
| 990 |
\& $lh\->denylist(\*(Aqnumf\*(Aq); |
| 991 |
\& $lh\->maketext(\*(Aq[_1] [numerate,_1,shoe,shoes]\*(Aq, 12); # dies |
| 992 |
.Ve |
| 993 |
.PP |
| 994 |
For lexicons that use an internal cache, translations which have already |
| 995 |
been cached in their compiled form are not affected by subsequent changes |
| 996 |
to the allowlist or denylist settings. Lexicons that use an external |
| 997 |
cache will have their cache cleared whenever the allowlist or denylist |
| 998 |
settings change. The difference between the two types of caching is explained |
| 999 |
in the "Readonly Lexicons" section. |
| 1000 |
.PP |
| 1001 |
Methods disallowed by the denylist cannot be permitted by the |
| 1002 |
allowlist. |
| 1003 |
.PP |
| 1004 |
NOTE: \fBdenylist()\fR is the preferred method name to use instead of the |
| 1005 |
historical and non-inclusive method \fBblacklist()\fR. \fBblacklist()\fR may be |
| 1006 |
removed in a future release of this package and so it's use should be |
| 1007 |
removed from usage. |
| 1008 |
.PP |
| 1009 |
NOTE: \fBallowlist()\fR is the preferred method name to use instead of the |
| 1010 |
historical and non-inclusive method \fBwhitelist()\fR. \fBwhitelist()\fR may be |
| 1011 |
removed in a future release of this package and so it's use should be |
| 1012 |
removed from usage. |
| 1013 |
.SH "AUTO LEXICONS" |
| 1014 |
.IX Header "AUTO LEXICONS" |
| 1015 |
If maketext goes to look in an individual \f(CW%Lexicon\fR for an entry |
| 1016 |
for \fIkey\fR (where \fIkey\fR does not start with an underscore), and |
| 1017 |
sees none, \fBbut does see\fR an entry of "_AUTO" => \fIsome_true_value\fR, |
| 1018 |
then we actually define \f(CW$Lexicon\fR{\fIkey\fR} = \fIkey\fR right then and there, |
| 1019 |
and then use that value as if it had been there all |
| 1020 |
along. This happens before we even look in any superclass \f(CW%Lexicons\fR! |
| 1021 |
.PP |
| 1022 |
(This is meant to be somewhat like the AUTOLOAD mechanism in |
| 1023 |
Perl's function call system \-\- or, looked at another way, |
| 1024 |
like the AutoLoader module.) |
| 1025 |
.PP |
| 1026 |
I can picture all sorts of circumstances where you just |
| 1027 |
do not want lookup to be able to fail (since failing |
| 1028 |
normally means that maketext throws a \f(CW\*(C`die\*(C'\fR, although |
| 1029 |
see the next section for greater control over that). But |
| 1030 |
here's one circumstance where _AUTO lexicons are meant to |
| 1031 |
be \fIespecially\fR useful: |
| 1032 |
.PP |
| 1033 |
As you're writing an application, you decide as you go what messages |
| 1034 |
you need to emit. Normally you'd go to write this: |
| 1035 |
.PP |
| 1036 |
.Vb 5 |
| 1037 |
\& if(\-e $filename) { |
| 1038 |
\& go_process_file($filename) |
| 1039 |
\& } else { |
| 1040 |
\& print qq{Couldn\*(Aqt find file "$filename"!\en}; |
| 1041 |
\& } |
| 1042 |
.Ve |
| 1043 |
.PP |
| 1044 |
but since you anticipate localizing this, you write: |
| 1045 |
.PP |
| 1046 |
.Vb 10 |
| 1047 |
\& use ThisProject::I18N; |
| 1048 |
\& my $lh = ThisProject::I18N\->get_handle(); |
| 1049 |
\& # For the moment, assume that things are set up so |
| 1050 |
\& # that we load class ThisProject::I18N::en |
| 1051 |
\& # and that that\*(Aqs the class that $lh belongs to. |
| 1052 |
\& ... |
| 1053 |
\& if(\-e $filename) { |
| 1054 |
\& go_process_file($filename) |
| 1055 |
\& } else { |
| 1056 |
\& print $lh\->maketext( |
| 1057 |
\& qq{Couldn\*(Aqt find file "[_1]"!\en}, $filename |
| 1058 |
\& ); |
| 1059 |
\& } |
| 1060 |
.Ve |
| 1061 |
.PP |
| 1062 |
Now, right after you've just written the above lines, you'd |
| 1063 |
normally have to go open the file |
| 1064 |
ThisProject/I18N/en.pm, and immediately add an entry: |
| 1065 |
.PP |
| 1066 |
.Vb 2 |
| 1067 |
\& "Couldn\*(Aqt find file \e"[_1]\e"!\en" |
| 1068 |
\& => "Couldn\*(Aqt find file \e"[_1]\e"!\en", |
| 1069 |
.Ve |
| 1070 |
.PP |
| 1071 |
But I consider that somewhat of a distraction from the work |
| 1072 |
of getting the main code working \-\- to say nothing of the fact |
| 1073 |
that I often have to play with the program a few times before |
| 1074 |
I can decide exactly what wording I want in the messages (which |
| 1075 |
in this case would require me to go changing three lines of code: |
| 1076 |
the call to maketext with that key, and then the two lines in |
| 1077 |
ThisProject/I18N/en.pm). |
| 1078 |
.PP |
| 1079 |
However, if you set "_AUTO => 1" in the \f(CW%Lexicon\fR in, |
| 1080 |
ThisProject/I18N/en.pm (assuming that English (en) is |
| 1081 |
the language that all your programmers will be using for this |
| 1082 |
project's internal message keys), then you don't ever have to |
| 1083 |
go adding lines like this |
| 1084 |
.PP |
| 1085 |
.Vb 2 |
| 1086 |
\& "Couldn\*(Aqt find file \e"[_1]\e"!\en" |
| 1087 |
\& => "Couldn\*(Aqt find file \e"[_1]\e"!\en", |
| 1088 |
.Ve |
| 1089 |
.PP |
| 1090 |
to ThisProject/I18N/en.pm, because if _AUTO is true there, |
| 1091 |
then just looking for an entry with the key "Couldn't find |
| 1092 |
file \e"[_1]\e"!\en" in that lexicon will cause it to be added, |
| 1093 |
with that value! |
| 1094 |
.PP |
| 1095 |
Note that the reason that keys that start with "_" |
| 1096 |
are immune to _AUTO isn't anything generally magical about |
| 1097 |
the underscore character \-\- I just wanted a way to have most |
| 1098 |
lexicon keys be autoable, except for possibly a few, and I |
| 1099 |
arbitrarily decided to use a leading underscore as a signal |
| 1100 |
to distinguish those few. |
| 1101 |
.SH "READONLY LEXICONS" |
| 1102 |
.IX Header "READONLY LEXICONS" |
| 1103 |
If your lexicon is a tied hash the simple act of caching the compiled value can be fatal. |
| 1104 |
.PP |
| 1105 |
For example a GDBM_File GDBM_READER tied hash will die with something like: |
| 1106 |
.PP |
| 1107 |
.Vb 1 |
| 1108 |
\& gdbm store returned \-1, errno 2, key "..." at ... |
| 1109 |
.Ve |
| 1110 |
.PP |
| 1111 |
All you need to do is turn on caching outside of the lexicon hash itself like so: |
| 1112 |
.PP |
| 1113 |
.Vb 6 |
| 1114 |
\& sub init { |
| 1115 |
\& my ($lh) = @_; |
| 1116 |
\& ... |
| 1117 |
\& $lh\->{\*(Aquse_external_lex_cache\*(Aq} = 1; |
| 1118 |
\& ... |
| 1119 |
\& } |
| 1120 |
.Ve |
| 1121 |
.PP |
| 1122 |
And then instead of storing the compiled value in the lexicon hash it will store it in \f(CW$lh\fR\->{'_external_lex_cache'} |
| 1123 |
.SH "CONTROLLING LOOKUP FAILURE" |
| 1124 |
.IX Header "CONTROLLING LOOKUP FAILURE" |
| 1125 |
If you call \f(CW$lh\fR\->maketext(\fIkey\fR, ...parameters...), |
| 1126 |
and there's no entry \fIkey\fR in \f(CW$lh\fR's class's \f(CW%Lexicon\fR, nor |
| 1127 |
in the superclass \f(CW%Lexicon\fR hash, \fIand\fR if we can't auto-make |
| 1128 |
\&\fIkey\fR (because either it starts with a "_", or because none |
| 1129 |
of its lexicons have \f(CW\*(C`_AUTO => 1,\*(C'\fR), then we have |
| 1130 |
failed to find a normal way to maketext \fIkey\fR. What then |
| 1131 |
happens in these failure conditions, depends on the \f(CW$lh\fR object's |
| 1132 |
"fail" attribute. |
| 1133 |
.PP |
| 1134 |
If the language handle has no "fail" attribute, maketext |
| 1135 |
will simply throw an exception (i.e., it calls \f(CW\*(C`die\*(C'\fR, mentioning |
| 1136 |
the \fIkey\fR whose lookup failed, and naming the line number where |
| 1137 |
the calling \f(CW$lh\fR\->maketext(\fIkey\fR,...) was. |
| 1138 |
.PP |
| 1139 |
If the language handle has a "fail" attribute whose value is a |
| 1140 |
coderef, then \f(CW$lh\fR\->maketext(\fIkey\fR,...params...) gives up and calls: |
| 1141 |
.PP |
| 1142 |
.Vb 1 |
| 1143 |
\& return $that_subref\->($lh, $key, @params); |
| 1144 |
.Ve |
| 1145 |
.PP |
| 1146 |
Otherwise, the "fail" attribute's value should be a string denoting |
| 1147 |
a method name, so that \f(CW$lh\fR\->maketext(\fIkey\fR,...params...) can |
| 1148 |
give up with: |
| 1149 |
.PP |
| 1150 |
.Vb 1 |
| 1151 |
\& return $lh\->$that_method_name($phrase, @params); |
| 1152 |
.Ve |
| 1153 |
.PP |
| 1154 |
The "fail" attribute can be accessed with the \f(CW\*(C`fail_with\*(C'\fR method: |
| 1155 |
.PP |
| 1156 |
.Vb 2 |
| 1157 |
\& # Set to a coderef: |
| 1158 |
\& $lh\->fail_with( \e&failure_handler ); |
| 1159 |
\& |
| 1160 |
\& # Set to a method name: |
| 1161 |
\& $lh\->fail_with( \*(Aqfailure_method\*(Aq ); |
| 1162 |
\& |
| 1163 |
\& # Set to nothing (i.e., so failure throws a plain exception) |
| 1164 |
\& $lh\->fail_with( undef ); |
| 1165 |
\& |
| 1166 |
\& # Get the current value |
| 1167 |
\& $handler = $lh\->fail_with(); |
| 1168 |
.Ve |
| 1169 |
.PP |
| 1170 |
Now, as to what you may want to do with these handlers: Maybe you'd |
| 1171 |
want to log what key failed for what class, and then die. Maybe |
| 1172 |
you don't like \f(CW\*(C`die\*(C'\fR and instead you want to send the error message |
| 1173 |
to STDOUT (or wherever) and then merely \f(CWexit()\fR. |
| 1174 |
.PP |
| 1175 |
Or maybe you don't want to \f(CW\*(C`die\*(C'\fR at all! Maybe you could use a |
| 1176 |
handler like this: |
| 1177 |
.PP |
| 1178 |
.Vb 10 |
| 1179 |
\& # Make all lookups fall back onto an English value, |
| 1180 |
\& # but only after we log it for later fingerpointing. |
| 1181 |
\& my $lh_backup = ThisProject\->get_handle(\*(Aqen\*(Aq); |
| 1182 |
\& open(LEX_FAIL_LOG, ">>wherever/lex.log") || die "GNAARGH $!"; |
| 1183 |
\& sub lex_fail { |
| 1184 |
\& my($failing_lh, $key, $params) = @_; |
| 1185 |
\& print LEX_FAIL_LOG scalar(localtime), "\et", |
| 1186 |
\& ref($failing_lh), "\et", $key, "\en"; |
| 1187 |
\& return $lh_backup\->maketext($key,@params); |
| 1188 |
\& } |
| 1189 |
.Ve |
| 1190 |
.PP |
| 1191 |
Some users have expressed that they think this whole mechanism of |
| 1192 |
having a "fail" attribute at all, seems a rather pointless complication. |
| 1193 |
But I want Locale::Maketext to be usable for software projects of \fIany\fR |
| 1194 |
scale and type; and different software projects have different ideas |
| 1195 |
of what the right thing is to do in failure conditions. I could simply |
| 1196 |
say that failure always throws an exception, and that if you want to be |
| 1197 |
careful, you'll just have to wrap every call to \f(CW$lh\fR\->maketext in an |
| 1198 |
eval\ {\ }. However, I want programmers to reserve the right (via |
| 1199 |
the "fail" attribute) to treat lookup failure as something other than |
| 1200 |
an exception of the same level of severity as a config file being |
| 1201 |
unreadable, or some essential resource being inaccessible. |
| 1202 |
.PP |
| 1203 |
One possibly useful value for the "fail" attribute is the method name |
| 1204 |
"failure_handler_auto". This is a method defined in the class |
| 1205 |
Locale::Maketext itself. You set it with: |
| 1206 |
.PP |
| 1207 |
.Vb 1 |
| 1208 |
\& $lh\->fail_with(\*(Aqfailure_handler_auto\*(Aq); |
| 1209 |
.Ve |
| 1210 |
.PP |
| 1211 |
Then when you call \f(CW$lh\fR\->maketext(\fIkey\fR, ...parameters...) and |
| 1212 |
there's no \fIkey\fR in any of those lexicons, maketext gives up with |
| 1213 |
.PP |
| 1214 |
.Vb 1 |
| 1215 |
\& return $lh\->failure_handler_auto($key, @params); |
| 1216 |
.Ve |
| 1217 |
.PP |
| 1218 |
But failure_handler_auto, instead of dying or anything, compiles |
| 1219 |
\&\f(CW$key\fR, caching it in |
| 1220 |
.PP |
| 1221 |
.Vb 1 |
| 1222 |
\& $lh\->{\*(Aqfailure_lex\*(Aq}{$key} = $compiled |
| 1223 |
.Ve |
| 1224 |
.PP |
| 1225 |
and then calls the compiled value, and returns that. (I.e., if |
| 1226 |
\&\f(CW$key\fR looks like bracket notation, \f(CW$compiled\fR is a sub, and we return |
| 1227 |
&{$compiled}(@params); but if \f(CW$key\fR is just a plain string, we just |
| 1228 |
return that.) |
| 1229 |
.PP |
| 1230 |
The effect of using "failure_auto_handler" |
| 1231 |
is like an AUTO lexicon, except that it 1) compiles \f(CW$key\fR even if |
| 1232 |
it starts with "_", and 2) you have a record in the new hashref |
| 1233 |
\&\f(CW$lh\fR\->{'failure_lex'} of all the keys that have failed for |
| 1234 |
this object. This should avoid your program dying \-\- as long |
| 1235 |
as your keys aren't actually invalid as bracket code, and as |
| 1236 |
long as they don't try calling methods that don't exist. |
| 1237 |
.PP |
| 1238 |
"failure_auto_handler" may not be exactly what you want, but I |
| 1239 |
hope it at least shows you that maketext failure can be mitigated |
| 1240 |
in any number of very flexible ways. If you can formalize exactly |
| 1241 |
what you want, you should be able to express that as a failure |
| 1242 |
handler. You can even make it default for every object of a given |
| 1243 |
class, by setting it in that class's init: |
| 1244 |
.PP |
| 1245 |
.Vb 9 |
| 1246 |
\& sub init { |
| 1247 |
\& my $lh = $_[0]; # a newborn handle |
| 1248 |
\& $lh\->SUPER::init(); |
| 1249 |
\& $lh\->fail_with(\*(Aqmy_clever_failure_handler\*(Aq); |
| 1250 |
\& return; |
| 1251 |
\& } |
| 1252 |
\& sub my_clever_failure_handler { |
| 1253 |
\& ...you clever things here... |
| 1254 |
\& } |
| 1255 |
.Ve |
| 1256 |
.SH "HOW TO USE MAKETEXT" |
| 1257 |
.IX Header "HOW TO USE MAKETEXT" |
| 1258 |
Here is a brief checklist on how to use Maketext to localize |
| 1259 |
applications: |
| 1260 |
.IP \(bu 4 |
| 1261 |
Decide what system you'll use for lexicon keys. If you insist, |
| 1262 |
you can use opaque IDs (if you're nostalgic for \f(CW\*(C`catgets\*(C'\fR), |
| 1263 |
but I have better suggestions in the |
| 1264 |
section "Entries in Each Lexicon", above. Assuming you opt for |
| 1265 |
meaningful keys that double as values (like "Minimum ([_1]) is |
| 1266 |
larger than maximum ([_2])!\en"), you'll have to settle on what |
| 1267 |
language those should be in. For the sake of argument, I'll |
| 1268 |
call this English, specifically American English, "en-US". |
| 1269 |
.IP \(bu 4 |
| 1270 |
Create a class for your localization project. This is |
| 1271 |
the name of the class that you'll use in the idiom: |
| 1272 |
.Sp |
| 1273 |
.Vb 2 |
| 1274 |
\& use Projname::L10N; |
| 1275 |
\& my $lh = Projname::L10N\->get_handle(...) || die "Language?"; |
| 1276 |
.Ve |
| 1277 |
.Sp |
| 1278 |
Assuming you call your class Projname::L10N, create a class |
| 1279 |
consisting minimally of: |
| 1280 |
.Sp |
| 1281 |
.Vb 3 |
| 1282 |
\& package Projname::L10N; |
| 1283 |
\& use base qw(Locale::Maketext); |
| 1284 |
\& ...any methods you might want all your languages to share... |
| 1285 |
\& |
| 1286 |
\& # And, assuming you want the base class to be an _AUTO lexicon, |
| 1287 |
\& # as is discussed a few sections up: |
| 1288 |
\& |
| 1289 |
\& 1; |
| 1290 |
.Ve |
| 1291 |
.IP \(bu 4 |
| 1292 |
Create a class for the language your internal keys are in. Name |
| 1293 |
the class after the language-tag for that language, in lowercase, |
| 1294 |
with dashes changed to underscores. Assuming your project's first |
| 1295 |
language is US English, you should call this Projname::L10N::en_us. |
| 1296 |
It should consist minimally of: |
| 1297 |
.Sp |
| 1298 |
.Vb 6 |
| 1299 |
\& package Projname::L10N::en_us; |
| 1300 |
\& use base qw(Projname::L10N); |
| 1301 |
\& %Lexicon = ( |
| 1302 |
\& \*(Aq_AUTO\*(Aq => 1, |
| 1303 |
\& ); |
| 1304 |
\& 1; |
| 1305 |
.Ve |
| 1306 |
.Sp |
| 1307 |
(For the rest of this section, I'll assume that this "first |
| 1308 |
language class" of Projname::L10N::en_us has |
| 1309 |
_AUTO lexicon.) |
| 1310 |
.IP \(bu 4 |
| 1311 |
Go and write your program. Everywhere in your program where |
| 1312 |
you would say: |
| 1313 |
.Sp |
| 1314 |
.Vb 1 |
| 1315 |
\& print "Foobar $thing stuff\en"; |
| 1316 |
.Ve |
| 1317 |
.Sp |
| 1318 |
instead do it thru maketext, using no variable interpolation in |
| 1319 |
the key: |
| 1320 |
.Sp |
| 1321 |
.Vb 1 |
| 1322 |
\& print $lh\->maketext("Foobar [_1] stuff\en", $thing); |
| 1323 |
.Ve |
| 1324 |
.Sp |
| 1325 |
If you get tired of constantly saying \f(CW\*(C`print $lh\->maketext\*(C'\fR, |
| 1326 |
consider making a functional wrapper for it, like so: |
| 1327 |
.Sp |
| 1328 |
.Vb 7 |
| 1329 |
\& use Projname::L10N; |
| 1330 |
\& our $lh; |
| 1331 |
\& $lh = Projname::L10N\->get_handle(...) || die "Language?"; |
| 1332 |
\& sub pmt (@) { print( $lh\->maketext(@_)) } |
| 1333 |
\& # "pmt" is short for "Print MakeText" |
| 1334 |
\& $Carp::Verbose = 1; |
| 1335 |
\& # so if maketext fails, we see made the call to pmt |
| 1336 |
.Ve |
| 1337 |
.Sp |
| 1338 |
Besides whole phrases meant for output, anything language-dependent |
| 1339 |
should be put into the class Projname::L10N::en_us, |
| 1340 |
whether as methods, or as lexicon entries \-\- this is discussed |
| 1341 |
in the section "Entries in Each Lexicon", above. |
| 1342 |
.IP \(bu 4 |
| 1343 |
Once the program is otherwise done, and once its localization for |
| 1344 |
the first language works right (via the data and methods in |
| 1345 |
Projname::L10N::en_us), you can get together the data for translation. |
| 1346 |
If your first language lexicon isn't an _AUTO lexicon, then you already |
| 1347 |
have all the messages explicitly in the lexicon (or else you'd be |
| 1348 |
getting exceptions thrown when you call \f(CW$lh\fR\->maketext to get |
| 1349 |
messages that aren't in there). But if you were (advisedly) lazy and are |
| 1350 |
using an _AUTO lexicon, then you've got to make a list of all the phrases |
| 1351 |
that you've so far been letting _AUTO generate for you. There are very |
| 1352 |
many ways to assemble such a list. The most straightforward is to simply |
| 1353 |
grep the source for every occurrence of "maketext" (or calls |
| 1354 |
to wrappers around it, like the above \f(CW\*(C`pmt\*(C'\fR function), and to log the |
| 1355 |
following phrase. |
| 1356 |
.IP \(bu 4 |
| 1357 |
You may at this point want to consider whether your base class |
| 1358 |
(Projname::L10N), from which all lexicons inherit from (Projname::L10N::en, |
| 1359 |
Projname::L10N::es, etc.), should be an _AUTO lexicon. It may be true |
| 1360 |
that in theory, all needed messages will be in each language class; |
| 1361 |
but in the presumably unlikely or "impossible" case of lookup failure, |
| 1362 |
you should consider whether your program should throw an exception, |
| 1363 |
emit text in English (or whatever your project's first language is), |
| 1364 |
or some more complex solution as described in the section |
| 1365 |
"Controlling Lookup Failure", above. |
| 1366 |
.IP \(bu 4 |
| 1367 |
Submit all messages/phrases/etc. to translators. |
| 1368 |
.Sp |
| 1369 |
(You may, in fact, want to start with localizing to \fIone\fR other language |
| 1370 |
at first, if you're not sure that you've properly abstracted the |
| 1371 |
language-dependent parts of your code.) |
| 1372 |
.Sp |
| 1373 |
Translators may request clarification of the situation in which a |
| 1374 |
particular phrase is found. For example, in English we are entirely happy |
| 1375 |
saying "\fIn\fR files found", regardless of whether we mean "I looked for files, |
| 1376 |
and found \fIn\fR of them" or the rather distinct situation of "I looked for |
| 1377 |
something else (like lines in files), and along the way I saw \fIn\fR |
| 1378 |
files." This may involve rethinking things that you thought quite clear: |
| 1379 |
should "Edit" on a toolbar be a noun ("editing") or a verb ("to edit")? Is |
| 1380 |
there already a conventionalized way to express that menu option, separate |
| 1381 |
from the target language's normal word for "to edit"? |
| 1382 |
.Sp |
| 1383 |
In all cases where the very common phenomenon of quantification |
| 1384 |
(saying "\fIN\fR files", for \fBany\fR value of N) |
| 1385 |
is involved, each translator should make clear what dependencies the |
| 1386 |
number causes in the sentence. In many cases, dependency is |
| 1387 |
limited to words adjacent to the number, in places where you might |
| 1388 |
expect them ("I found the\-?PLURAL \fIN\fR |
| 1389 |
empty\-?PLURAL directory\-?PLURAL"), but in some cases there are |
| 1390 |
unexpected dependencies ("I found\-?PLURAL ..."!) as well as long-distance |
| 1391 |
dependencies "The \fIN\fR directory\-?PLURAL could not be deleted\-?PLURAL"!). |
| 1392 |
.Sp |
| 1393 |
Remind the translators to consider the case where N is 0: |
| 1394 |
"0 files found" isn't exactly natural-sounding in any language, but it |
| 1395 |
may be unacceptable in many \-\- or it may condition special |
| 1396 |
kinds of agreement (similar to English "I didN'T find ANY files"). |
| 1397 |
.Sp |
| 1398 |
Remember to ask your translators about numeral formatting in their |
| 1399 |
language, so that you can override the \f(CW\*(C`numf\*(C'\fR method as |
| 1400 |
appropriate. Typical variables in number formatting are: what to |
| 1401 |
use as a decimal point (comma? period?); what to use as a thousands |
| 1402 |
separator (space? nonbreaking space? comma? period? small |
| 1403 |
middot? prime? apostrophe?); and even whether the so-called "thousands |
| 1404 |
separator" is actually for every third digit \-\- I've heard reports of |
| 1405 |
two hundred thousand being expressible as "2,00,000" for some Indian |
| 1406 |
(Subcontinental) languages, besides the less surprising "200\ 000", |
| 1407 |
"200.000", "200,000", and "200'000". Also, using a set of numeral |
| 1408 |
glyphs other than the usual ASCII "0"\-"9" might be appreciated, as via |
| 1409 |
\&\f(CW\*(C`tr/0\-9/\ex{0966}\-\ex{096F}/\*(C'\fR for getting digits in Devanagari script |
| 1410 |
(for Hindi, Konkani, others). |
| 1411 |
.Sp |
| 1412 |
The basic \f(CW\*(C`quant\*(C'\fR method that Locale::Maketext provides should be |
| 1413 |
good for many languages. For some languages, it might be useful |
| 1414 |
to modify it (or its constituent \f(CW\*(C`numerate\*(C'\fR method) |
| 1415 |
to take a plural form in the two-argument call to \f(CW\*(C`quant\*(C'\fR |
| 1416 |
(as in "[quant,_1,files]") if |
| 1417 |
it's all-around easier to infer the singular form from the plural, than |
| 1418 |
to infer the plural form from the singular. |
| 1419 |
.Sp |
| 1420 |
But for other languages (as is discussed at length |
| 1421 |
in Locale::Maketext::TPJ13), simple |
| 1422 |
\&\f(CW\*(C`quant\*(C'\fR/\f(CW\*(C`numf\*(C'\fR is not enough. For the particularly problematic |
| 1423 |
Slavic languages, what you may need is a method which you provide |
| 1424 |
with the number, the citation form of the noun to quantify, and |
| 1425 |
the case and gender that the sentence's syntax projects onto that |
| 1426 |
noun slot. The method would then be responsible for determining |
| 1427 |
what grammatical number that numeral projects onto its noun phrase, |
| 1428 |
and what case and gender it may override the normal case and gender |
| 1429 |
with; and then it would look up the noun in a lexicon providing |
| 1430 |
all needed inflected forms. |
| 1431 |
.IP \(bu 4 |
| 1432 |
You may also wish to discuss with the translators the question of |
| 1433 |
how to relate different subforms of the same language tag, |
| 1434 |
considering how this reacts with \f(CW\*(C`get_handle\*(C'\fR's treatment of |
| 1435 |
these. For example, if a user accepts interfaces in "en, fr", and |
| 1436 |
you have interfaces available in "en-US" and "fr", what should |
| 1437 |
they get? You may wish to resolve this by establishing that "en" |
| 1438 |
and "en-US" are effectively synonymous, by having one class |
| 1439 |
zero-derive from the other. |
| 1440 |
.Sp |
| 1441 |
For some languages this issue may never come up (Danish is rarely |
| 1442 |
expressed as "da-DK", but instead is just "da"). And for other |
| 1443 |
languages, the whole concept of a "generic" form may verge on |
| 1444 |
being uselessly vague, particularly for interfaces involving voice |
| 1445 |
media in forms of Arabic or Chinese. |
| 1446 |
.IP \(bu 4 |
| 1447 |
Once you've localized your program/site/etc. for all desired |
| 1448 |
languages, be sure to show the result (whether live, or via |
| 1449 |
screenshots) to the translators. Once they approve, make every |
| 1450 |
effort to have it then checked by at least one other speaker of |
| 1451 |
that language. This holds true even when (or especially when) the |
| 1452 |
translation is done by one of your own programmers. Some |
| 1453 |
kinds of systems may be harder to find testers for than others, |
| 1454 |
depending on the amount of domain-specific jargon and concepts |
| 1455 |
involved \-\- it's easier to find people who can tell you whether |
| 1456 |
they approve of your translation for "delete this message" in an |
| 1457 |
email-via-Web interface, than to find people who can give you |
| 1458 |
an informed opinion on your translation for "attribute value" |
| 1459 |
in an XML query tool's interface. |
| 1460 |
.SH "SEE ALSO" |
| 1461 |
.IX Header "SEE ALSO" |
| 1462 |
I recommend reading all of these: |
| 1463 |
.PP |
| 1464 |
Locale::Maketext::TPJ13 \-\- my \fIThe Perl |
| 1465 |
Journal\fR article about Maketext. It explains many important concepts |
| 1466 |
underlying Locale::Maketext's design, and some insight into why |
| 1467 |
Maketext is better than the plain old approach of having |
| 1468 |
message catalogs that are just databases of sprintf formats. |
| 1469 |
.PP |
| 1470 |
File::Findgrep is a sample application/module |
| 1471 |
that uses Locale::Maketext to localize its messages. For a larger |
| 1472 |
internationalized system, see also Apache::MP3. |
| 1473 |
.PP |
| 1474 |
I18N::LangTags. |
| 1475 |
.PP |
| 1476 |
Win32::Locale. |
| 1477 |
.PP |
| 1478 |
RFC 3066, \fITags for the Identification of Languages\fR, |
| 1479 |
as at <http://sunsite.dk/RFC/rfc/rfc3066.html> |
| 1480 |
.PP |
| 1481 |
RFC 2277, \fIIETF Policy on Character Sets and Languages\fR |
| 1482 |
is at <http://sunsite.dk/RFC/rfc/rfc2277.html> \-\- much of it is |
| 1483 |
just things of interest to protocol designers, but it explains |
| 1484 |
some basic concepts, like the distinction between locales and |
| 1485 |
language-tags. |
| 1486 |
.PP |
| 1487 |
The manual for GNU \f(CW\*(C`gettext\*(C'\fR. The gettext dist is available in |
| 1488 |
\&\f(CW\*(C`<ftp://prep.ai.mit.edu/pub/gnu/>\*(C'\fR \-\- get |
| 1489 |
a recent gettext tarball and look in its "doc/" directory, there's |
| 1490 |
an easily browsable HTML version in there. The |
| 1491 |
gettext documentation asks lots of questions worth thinking |
| 1492 |
about, even if some of their answers are sometimes wonky, |
| 1493 |
particularly where they start talking about pluralization. |
| 1494 |
.PP |
| 1495 |
The Locale/Maketext.pm source. Observe that the module is much |
| 1496 |
shorter than its documentation! |
| 1497 |
.SH "COPYRIGHT AND DISCLAIMER" |
| 1498 |
.IX Header "COPYRIGHT AND DISCLAIMER" |
| 1499 |
Copyright (c) 1999\-2004 Sean M. Burke. All rights reserved. |
| 1500 |
.PP |
| 1501 |
This library is free software; you can redistribute it and/or modify |
| 1502 |
it under the same terms as Perl itself. |
| 1503 |
.PP |
| 1504 |
This program is distributed in the hope that it will be useful, but |
| 1505 |
without any warranty; without even the implied warranty of |
| 1506 |
merchantability or fitness for a particular purpose. |
| 1507 |
.SH AUTHOR |
| 1508 |
.IX Header "AUTHOR" |
| 1509 |
Sean M. Burke \f(CW\*(C`[email protected]\*(C'\fR |