Debian Codegraph @

dist/Locale-Maketext/lib/Locale/Maketext/Cookbook.pod

raw
1 # This document contains text in Perl "POD" format.
2 # Use a POD viewer like perldoc or perlman to render it.
3
4 =encoding utf-8
5
6 =head1 NAME
7
8 Locale::Maketext::Cookbook - recipes for using Locale::Maketext
9
10 =head1 INTRODUCTION
11
12 This is a work in progress. Not much progress by now :-)
13
14 =head1 ONESIDED LEXICONS
15
16 I<Adapted from a suggestion by Dan Muey>
17
18 It may be common (for example at your main lexicon) that
19 the hash keys and values coincide. Like that
20
21 q{Hello, tell me your name}
22 => q{Hello, tell me your name}
23
24 It would be nice to just write:
25
26 q{Hello, tell me your name} => ''
27
28 and have this magically inflated to the first form.
29 Among the advantages of such representation, that would
30 lead to
31 smaller files, less prone to mistyping or mispasting,
32 and handy to someone translating it which can simply
33 copy the main lexicon and enter the translation
34 instead of having to remove the value first.
35
36 That can be achieved by overriding C<init>
37 in your class and working on the main lexicon
38 with code like that:
39
40 package My::I18N;
41 ...
42
43 sub init {
44 my $lh = shift; # a newborn handle
45 $lh->SUPER::init();
46 inflate_lexicon(\%My::I18N::en::Lexicon);
47 return;
48 }
49
50 sub inflate_lexicon {
51 my $lex = shift;
52 while (my ($k, $v) = each %$lex) {
53 $v = $k if !defined $v || $v eq '';
54 }
55 }
56
57 Here we are assuming C<My::I18N::en> to own the
58 main lexicon.
59
60 There are some downsides here: the size economy
61 will not stand at runtime after this C<init()>
62 runs. But it should not be that critical, since
63 if you don't have space for that, you won't have
64 space for any other language besides the main one
65 as well. You could do that too with ties,
66 expanding the value at lookup time which
67 should be more time expensive as an option.
68
69 =head1 DECIMAL PLACES IN NUMBER FORMATTING
70
71 I<After CPAN RT #36136 (L<https://rt.cpan.org/Ticket/Display.html?id=36136>)>
72
73 The documentation of L<Locale::Maketext> advises that
74 the standard bracket method C<numf> is limited and that
75 you must override that for better results. It even
76 suggests the use of L<Number::Format>.
77
78 One such defect of standard C<numf> is to not be
79 able to use a certain decimal precision.
80 For example,
81
82 $lh->maketext('pi is [numf,_1]', 355/113);
83
84 outputs
85
86 pi is 3.14159292035398
87
88 Since pi ≈ 355/116 is only accurate
89 to 6 decimal places, you would want to say:
90
91 $lh->maketext('pi is [numf,_1,6]', 355/113);
92
93 and get "pi is 3.141592".
94
95 One solution for that could use C<Number::Format>
96 like that:
97
98 package Wuu;
99
100 use base qw(Locale::Maketext);
101
102 use Number::Format;
103
104 # can be overridden according to language conventions
105 sub _numf_params {
106 return (
107 -thousands_sep => '.',
108 -decimal_point => ',',
109 -decimal_digits => 2,
110 );
111 }
112
113 # builds a Number::Format
114 sub _numf_formatter {
115 my ($lh, $scale) = @_;
116 my @params = $lh->_numf_params;
117 if ($scale) { # use explicit scale rather than default
118 push @params, (-decimal_digits => $scale);
119 }
120 return Number::Format->new(@params);
121 }
122
123 sub numf {
124 my ($lh, $n, $scale) = @_;
125 # get the (cached) formatter
126 my $nf = $lh->{__nf}{$scale} ||= $lh->_numf_formatter($scale);
127 # format the number itself
128 return $nf->format_number($n);
129 }
130
131 package Wuu::pt;
132
133 use base qw(Wuu);
134
135 and then
136
137 my $lh = Wuu->get_handle('pt');
138 $lh->maketext('A [numf,_1,3] km de distância', 1550.2222);
139
140 would return "A 1.550,222 km de distância".
141
142 Notice that the standard utility methods of
143 C<Locale::Maketext> are irremediably limited
144 because they could not aim to do everything
145 that could be expected from them in different languages,
146 cultures and applications. So extending C<numf>,
147 C<quant>, and C<sprintf> is natural as soon
148 as your needs exceed what the standard ones do.
149
150