1Locale::Po4a::TransTractor(3pm) Po4a Tools Locale::Po4a::TransTractor(3pm)
2
6 Locale::Po4a::TransTractor - generic trans(lator ex)tractor.
7
9 The po4a (PO for anything) project goal is to ease translations (and
10 more interestingly, the maintenance of translations) using gettext
11 tools on areas where they were not expected like documentation.
12 This class is the ancestor of every po4a parser used to parse a
14 document, to search translatable strings, to extract them to a PO file
15 and to replace them by their translation in the output document.
16 More formally, it takes the following arguments as input:
18 - a document to translate;
20 - a PO file containing the translations to use.
22 As output, it produces:
24 - another PO file, resulting of the extraction of translatable strings
26 from the input document;
27 - a translated document, with the same structure than the one in input,
29 but with all translatable strings replaced with the translations
30 found in the PO file provided in input.
31 Here is a graphical representation of this:
33 Input document --\ /---> Output document
35 \ / (translated)
36 +-> parse() function -----+
37 / \
38 Input PO --------/ \---> Output PO
39 (extracted)
40
42 parse()
43 This is where all the work takes place: the parsing of input
44 documents, the generation of output, and the extraction of the
45 translatable strings. This is pretty simple using the provided
46 functions presented in the section INTERNAL FUNCTIONS below. See
47 also the SYNOPSIS, which presents an example.
48 This function is called by the process() function below, but if you
50 choose to use the new() function, and to add content manually to
51 your document, you will have to call this function yourself.
52 docheader()
54 This function returns the header we should add to the produced
55 document, quoted properly to be a comment in the target language.
56 See the section Educating developers about translations, from
57 po4a(7), for what it is good for.
58
60 The following example parses a list of paragraphs beginning with "<p>".
61 For the sake of simplicity, we assume that the document is well
62 formatted, i.e. that '<p>' tags are the only tags present, and that
63 this tag is at the very beginning of each paragraph.
64 sub parse {
66 my $self = shift;
67 PARAGRAPH: while (1) {
69 my ($paragraph,$pararef)=("","");
70 my $first=1;
71 my ($line,$lref)=$self->shiftline();
72 while (defined($line)) {
73 if ($line =~ m/<p>/ && !$first--; ) {
74 # Not the first time we see <p>.
75 # Reput the current line in input,
76 # and put the built paragraph to output
77 $self->unshiftline($line,$lref);
78 # Now that the document is formed, translate it:
80 # - Remove the leading tag
81 $paragraph =~ s/^<p>//s;
82 # - push to output the leading tag (untranslated) and the
84 # rest of the paragraph (translated)
85 $self->pushline( "<p>"
86 . $self->translate($paragraph,$pararef)
87 );
88 next PARAGRAPH;
90 } else {
91 # Append to the paragraph
92 $paragraph .= $line;
93 $pararef = $lref unless(length($pararef));
94 }
95 # Reinit the loop
97 ($line,$lref)=$self->shiftline();
98 }
99 # Did not get a defined line? End of input file.
100 return;
101 }
102 }
103 Once you've implemented the parse function, you can use your document
105 class, using the public interface presented in the next section.
106
108 Constructor
109 process(%)
110 This function can do all you need to do with a po4a document in one
111 invocation. Its arguments must be packed as a hash. ACTIONS:
112 a. Reads all the PO files specified in po_in_name
114 b. Reads all original documents specified in file_in_name
116 c. Parses the document
118 d. Reads and applies all the addenda specified
120 e. Writes the translated document to file_out_name (if given)
122 f. Writes the extracted PO file to po_out_name (if given)
124 ARGUMENTS, beside the ones accepted by new() (with expected type):
126 file_in_name (@)
128 List of filenames where we should read the input document.
129 file_in_charset ($)
131 Charset used in the input document (if it isn't specified, it
132 will try to detect it from the input document).
133 file_out_name ($)
135 Filename where we should write the output document.
136 file_out_charset ($)
138 Charset used in the output document (if it isn't specified, it
139 will use the PO file charset).
140 po_in_name (@)
142 List of filenames where we should read the input PO files from,
143 containing the translation which will be used to translate the
144 document.
145 po_out_name ($)
147 Filename where we should write the output PO file, containing
148 the strings extracted from the input document.
149 addendum (@)
151 List of filenames where we should read the addenda from.
152 addendum_charset ($)
154 Charset for the addenda.
155 new(%)
157 Create a new po4a document. Accepted options (in the hash passed as
158 a parameter):
159 verbose ($)
161 Sets the verbosity.
162 debug ($)
164 Sets the debugging.
165 Manipulating document files
167 read($$)
168 Add another input document data at the end of the existing array
169 "@{$self->{TT}{doc_in}}". The argument is the filename to read. If
170 a second argument is provided, it is the filename to use in the
171 references.
172 This array "@{$self->{TT}{doc_in}}" holds this input document data
174 as an array of strings with alternating meanings.
175 * The string $textline holding each line of the input text data.
176 * The string "$filename:$linenum" holding its location and called
177 as
178 "reference" ("linenum" starts with 1).
179 Please note that it does not parse anything. You should use the
181 parse() function when you're done with packing input files into the
182 document.
183 write($)
185 Write the translated document to the given filename.
186 This translated document data are provided by:
188 * "$self->docheader()" holding the header text for the plugin, and
189 * "@{$self->{TT}{doc_out}}" holding each line of the main
190 translated text in the array.
191 Manipulating PO files
193 readpo($)
194 Add the content of a file (which name is passed as argument) to the
195 existing input PO. The old content is not discarded.
196 writepo($)
198 Write the extracted PO file to the given filename.
199 stats()
201 Returns some statistics about the translation done so far. Please
202 note that it's not the same statistics than the one printed by
203 msgfmt --statistic. Here, it's stats about recent usage of the PO
204 file, while msgfmt reports the status of the file. It is a wrapper
205 to the Locale::Po4a::Po::stats_get function applied to the input PO
206 file. Example of use:
207 [normal use of the po4a document...]
209 ($percent,$hit,$queries) = $document->stats();
211 print "We found translations for $percent\% ($hit from $queries) of strings.\n";
212 is_po_uptodate()
214 Returns ($uptodate, $diagnostic) where $uptodate is whether the
215 input po and the output po match (if not, it means that the input
216 po should be updated) and $diagnostic is a string explaining why
217 the po file is not uptodate, when this happens.
218 Manipulating addenda
220 addendum($)
221 Please refer to po4a(7) for more information on what addenda are,
222 and how translators should write them. To apply an addendum to the
223 translated document, simply pass its filename to this function and
224 you are done ;)
225 This function returns a non-null integer on error.
227
229 Getting input, providing output
230 Four functions are provided to get input and return output. They are
231 very similar to shift/unshift and push/pop of Perl.
232 * Perl shift returns the first array item and drop it from the array.
234 * Perl unshift prepends an item to the array as the first array item.
235 * Perl pop returns the last array item and drop it from the array.
236 * Perl push appends an item to the array as the last array item.
237 The first pair is about input, while the second is about output.
239 Mnemonic: in input, you are interested in the first line, what shift
240 gives, and in output you want to add your result at the end, like push
241 does.
242 shiftline()
244 This function returns the first line to be parsed and its
245 corresponding reference (packed as an array) from the array
246 "@{$self->{TT}{doc_in}}" and drop these first 2 array items. Here,
247 the reference is provided by a string "$filename:$linenum".
248 unshiftline($$)
250 Unshifts the last shifted line of the input document and its
251 corresponding reference back to the head of
252 "{$self->{TT}{doc_in}}".
253 pushline($)
255 Push a new line to the end of "{$self->{TT}{doc_out}}".
256 popline()
258 Pop the last pushed line from the end of "{$self->{TT}{doc_out}}".
259 Marking strings as translatable
261 One function is provided to handle the text which should be translated.
262 translate($$$)
264 Mandatory arguments:
265 - A string to translate
267 - The reference of this string (i.e. position in inputfile)
269 - The type of this string (i.e. the textual description of its
271 structural role; used in Locale::Po4a::Po::gettextization(); see
272 also po4a(7), section Gettextization: how does it work?)
273 This function can also take some extra arguments. They must be
275 organized as a hash. For example:
276 $self->translate("string","ref","type",
278 'wrap' => 1);
279 wrap
281 boolean indicating whether we can consider that whitespaces in
282 string are not important. If yes, the function canonizes the
283 string before looking for a translation or extracting it, and
284 wraps the translation.
285 wrapcol
287 the column at which we should wrap (default: 76).
288 comment
290 an extra comment to add to the entry.
291 Actions:
293 - Pushes the string, reference and type to po_out.
295 - Returns the translation of the string (as found in po_in) so that
297 the parser can build the doc_out.
298 - Handles the charsets to recode the strings before sending them to
300 po_out and before returning the translations.
301 Misc functions
303 verbose()
304 Returns if the verbose option was passed during the creation of the
305 TransTractor.
306 debug()
308 Returns if the debug option was passed during the creation of the
309 TransTractor.
310 detected_charset($)
312 This tells TransTractor that a new charset (the first argument) has
313 been detected from the input document. It can usually be read from
314 the document header. Only the first charset will remain, coming
315 either from the process() arguments or detected from the document.
316 get_out_charset()
318 This function will return the charset that should be used in the
319 output document (usually useful to substitute the input document's
320 detected charset where it has been found).
321 It will use the output charset specified in the command line. If it
323 wasn't specified, it will use the input PO's charset, and if the
324 input PO has the default "CHARSET", it will return the input
325 document's charset, so that no encoding is performed.
326 recode_skipped_text($)
328 This function returns the recoded text passed as argument, from the
329 input document's charset to the output document's one. This isn't
330 needed when translating a string (translate() recodes everything
331 itself), but it is when you skip a string from the input document
332 and you want the output document to be consistent with the global
333 encoding.
334
336 One shortcoming of the current TransTractor is that it can't handle
337 translated document containing all languages, like debconf templates,
338 or .desktop files.
339 To address this problem, the only interface changes needed are:
341 - take a hash as po_in_name (a list per language)
343 - add an argument to translate to indicate the target language
345 - make a pushline_all function, which would make pushline of its
347 content for all languages, using a map-like syntax:
348 $self->pushline_all({ "Description[".$langcode."]=".
350 $self->translate($line,$ref,$langcode)
351 });
352 Will see if it's enough ;)
354
356 Denis Barbier <barbier@linuxfr.org>
357 Martin Quinson (mquinson#debian.org)
358 Jordi Vilalta <jvprat@gmail.com>
359Po4a Tools 2022-01-21 Locale::Po4a::TransTractor(3pm)