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
8Locale::Maketext::Cookbook - recipes for using Locale::Maketext
9
10=head1 INTRODUCTION
11
12This is a work in progress. Not much progress by now :-)
13
14=head1 ONESIDED LEXICONS
15
16I<Adapted from a suggestion by Dan Muey>
17
18It may be common (for example at your main lexicon) that
19the hash keys and values coincide. Like that
20
21    q{Hello, tell me your name}
22      => q{Hello, tell me your name}
23
24It would be nice to just write:
25
26    q{Hello, tell me your name} => ''
27
28and have this magically inflated to the first form.
29Among the advantages of such representation, that would
30lead to
31smaller files, less prone to mistyping or mispasting,
32and handy to someone translating it which can simply
33copy the main lexicon and enter the translation
34instead of having to remove the value first.
35
36That can be achieved by overriding C<init>
37in your class and working on the main lexicon
38with 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
57Here we are assuming C<My::I18N::en> to own the
58main lexicon.
59
60There are some downsides here: the size economy
61will not stand at runtime after this C<init()>
62runs. But it should not be that critical, since
63if you don't have space for that, you won't have
64space for any other language besides the main one
65as well. You could do that too with ties,
66expanding the value at lookup time which
67should be more time expensive as an option.
68
69=head1 DECIMAL PLACES IN NUMBER FORMATTING
70
71I<After CPAN RT #36136 (L<https://rt.cpan.org/Ticket/Display.html?id=36136>)>
72
73The documentation of L<Locale::Maketext> advises that
74the standard bracket method C<numf> is limited and that
75you must override that for better results. It even
76suggests the use of L<Number::Format>.
77
78One such defect of standard C<numf> is to not be
79able to use a certain decimal precision.
80For example,
81
82    $lh->maketext('pi is [numf,_1]', 355/113);
83
84outputs
85
86    pi is 3.14159292035398
87
88Since pi ≈ 355/116 is only accurate
89to 6 decimal places, you would want to say:
90
91    $lh->maketext('pi is [numf,_1,6]', 355/113);
92
93and get "pi is 3.141592".
94
95One solution for that could use C<Number::Format>
96like 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
135and then
136
137    my $lh = Wuu->get_handle('pt');
138    $lh->maketext('A [numf,_1,3] km de distância', 1550.2222);
139
140would return "A 1.550,222 km de distância".
141
142Notice that the standard utility methods of
143C<Locale::Maketext> are irremediably limited
144because they could not aim to do everything
145that could be expected from them in different languages,
146cultures and applications. So extending C<numf>,
147C<quant>, and C<sprintf> is natural as soon
148as your needs exceed what the standard ones do.
149
150
151