Locale::Maketext::Fuzzy(3pm)

1Locale::Maketext::FuzzyU(s3e)r Contributed Perl DocumentaLtoicoanle::Maketext::Fuzzy(3)
2
3
4

NAME

6       Locale::Maketext::Fuzzy - Maketext from already interpolated strings
7

SYNOPSIS

9           package MyApp::L10N;
10           use base 'Locale::Maketext::Fuzzy'; # instead of Locale::Maketext
11
12           package MyApp::L10N::de;
13           use base 'MyApp::L10N';
14           our %Lexicon = (
15               # Exact match should always be preferred if possible
16               "0 camels were released."
17                   => "Exact match",
18
19               # Fuzzy match candidate
20               "[quant,_1,camel was,camels were] released."
21                   => "[quant,_1,Kamel wurde,Kamele wurden] freigegeben.",
22
23               # This could also match fuzzily, but is less preferred
24               "[_2] released[_1]"
25                   => "[_1][_2] ist frei[_1]",
26           );
27
28           package main;
29           my $lh = MyApp::L10N->get_handle('de');
30
31           # All ->maketext calls below will become ->maketext_fuzzy instead
32           $lh->override_maketext(1);
33
34           # This prints "Exact match"
35           print $lh->maketext('0 camels were released.');
36
37           # "1 Kamel wurde freigegeben." -- quant() gets 1
38           print $lh->maketext('1 camel was released.');
39
40           # "2 Kamele wurden freigegeben." -- quant() gets 2
41           print $lh->maketext('2 camels were released.');
42
43           # "3 Kamele wurden freigegeben." -- parameters are ignored
44           print $lh->maketext('3 released.');
45
46           # "4 Kamele wurden freigegeben." -- normal usage
47           print $lh->maketext('[*,_1,camel was,camels were] released.', 4);
48
49           # "!Perl ist frei!" -- matches the broader one
50           # Note that the sequence ([_2] before [_1]) is preserved
51           print $lh->maketext('Perl released!');
52

DESCRIPTION

54       This module is a subclass of "Locale::Maketext", with additional
55       support for localizing messages that already contains interpolated
56       variables.
57
58       This is most useful when the messages are returned by external sources
59       -- for example, to match "dir: command not found" against "[_1]:
60       command not found".
61
62       Of course, this module is also useful if you're simply too lazy to use
63       the
64
65           $lh->maketext("[quant,_1,file,files] deleted.", $count);
66
67       syntax, but wish to write
68
69           $lh->maketext_fuzzy("$count files deleted");
70
71       instead, and have the correct plural form figured out automatically.
72
73       If "maketext_fuzzy" seems too long to type for you, this module also
74       provides a "override_maketext" method to turn all "maketext" calls into
75       "maketext_fuzzy" calls.
76

METHODS

78   $lh->maketext_fuzzy(key[, parameters...]);
79       That method takes exactly the same arguments as the "maketext" method
80       of "Locale::Maketext".
81
82       If key is found in lexicons, it is applied in the same way as
83       "maketext".  Otherwise, it looks at all lexicon entries that could
84       possibly yield key, by turning "[...]" sequences into "(.*?)" and match
85       the resulting regular expression against key.
86
87       Once it finds all candidate entries, the longest one replaces the key
88       for the real "maketext" call.  Variables matched by its bracket
89       sequences ($1, $2...) are placed before parameters; the order of
90       variables in the matched entry are correctly preserved.
91
92       For example, if the matched entry in %Lexicon is "Test [_1]", this
93       call:
94
95           $fh->maketext_fuzzy("Test string", "param");
96
97       is equivalent to this:
98
99           $fh->maketext("Test [_1]", "string", "param");
100
101       However, most of the time you won't need to supply parameters to a
102       "maketext_fuzzy" call, since all parameters are already interpolated
103       into the string.
104
105   $lh->override_maketext([flag]);
106       If flag is true, this accessor method turns "$lh->maketext" into an
107       alias for "$lh->maketext_fuzzy", so all consecutive "maketext" calls in
108       the $lh's packages are automatically fuzzy.  A false flag restores the
109       original behaviour.  If the flag is not specified, returns the current
110       status of override; the default is 0 (no overriding).
111
112       Note that this call only modifies the symbol table of the language
113       class that $lh belongs to, so other languages are not affected.  If you
114       want to override all language handles in a certain application, try
115       this:
116
117           MyApp::L10N->override_maketext(1);
118

CAVEATS

120       •   The "longer is better" heuristic to determine the best match is
121           reasonably good, but could certainly be improved.
122
123       •   Currently, "[quant,_1,file] deleted" won't match "3 files deleted";
124           you'll have to write "[quant,_1,file,files] deleted" instead, or
125           simply use "[_1] file deleted" as the lexicon key and put the
126           correct plural form handling into the corresponding value.
127
128       •   When used in combination with "Locale::Maketext::Lexicon"'s "Tie"
129           backend, all keys would be iterated over each time a fuzzy match is
130           performed, and may cause serious speed penalty.  Patches welcome.
131

HISTORY

136       This particular module was written to facilitate an auto-extraction
137       layer for Slashcode's Template Toolkit provider, based on
138       "HTML::Parser" and "Template::Parser".  It would work like this:
139
140           Input | <B>from the [% story.dept %] dept.</B>
141           Output| <B>[%|loc( story.dept )%]from the [_1] dept.[%END%]</B>
142
143       Now, this layer suffers from the same linguistic problems as an
144       ordinary "Msgcat" or "Gettext" framework does -- what if we want to
145       make ordinals from "[% story.dept %]" (i.e. "from the 3rd dept."), or
146       expand the "dept." to "department" / "departments"?
147
148       The same problem occurred in RT's web interface, where it had to
149       localize messages returned by external modules, which may already
150       contain interpolated variables, e.g. "Successfully deleted 7 ticket(s)
151       in 'c:\temp'.".
152
153       Since I didn't have the time to refactor "DBI" and
154       "DBI::SearchBuilder", I devised a "loc_match" method to pre-process
155       their messages into one of the candidate strings, then applied the
156       matched string to "maketext".
157
158       Afterwards, I realized that instead of preparing a set of candidate
159       strings, I could actually match against the original lexicon file (i.e.
160       PO files via "Locale::Maketext::Lexicon").  This is how
161       "Locale::Maketext::Fuzzy" was born.
162

AUTHORS

164       Audrey Tang <cpan@audreyt.org>
165

CC0 1.0 Universal

167       To the extent possible under law, 唐鳳 has waived all copyright and
168       related or neighboring rights to Locale-Maketext-Fuzzy.
169
170       This work is published from Taiwan.
171
172       <http://creativecommons.org/publicdomain/zero/1.0>
173

POD ERRORS

175       Hey! The above document had some coding errors, which are explained
176       below:
177
178       Around line 318:
179           Non-ASCII character seen before =encoding in '唐鳳'. Assuming UTF-8
180
181
182
183perl v5.38.0                      2023-07-20        Locale::Maketext::Fuzzy(3)