1Locale::Po4a::TransTractor(3pm)   Po4a Tools   Locale::Po4a::TransTractor(3pm)
2
3
4

NAME

6       Locale::Po4a::TransTractor - generic trans(lator ex)tractor.
7

DESCRIPTION

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
13       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
17       More formally, it takes the following arguments as input:
18
19       - a document to translate;
20
21       - a PO file containing the translations to use.
22
23       As output, it produces:
24
25       - another PO file, resulting of the extraction of translatable strings
26         from the input document;
27
28       - 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
32       Here is a graphical representation of this:
33
34          Input document --\                             /---> Output document
35                            \                           /       (translated)
36                             +-> parse() function -----+
37                            /                           \
38          Input PO --------/                             \---> Output PO
39                                                                (extracted)
40

FUNCTIONS YOUR PARSER SHOULD OVERRIDE

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
49           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
53       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

SYNOPSIS

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
65        sub parse {
66          my $self = shift;
67
68          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
79                      # Now that the document is formed, translate it:
80                      #   - Remove the leading tag
81                      $paragraph =~ s/^<p>//s;
82
83                      #   - 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
89                      next PARAGRAPH;
90                  } else {
91                      # Append to the paragraph
92                      $paragraph .= $line;
93                      $pararef = $lref unless(length($pararef));
94                  }
95
96                  # 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
104       Once you've implemented the parse function, you can use your document
105       class, using the public interface presented in the next section.
106

PUBLIC INTERFACE for scripts using your parser

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
113           a. Reads all the PO files specified in po_in_name
114
115           b. Reads all original documents specified in file_in_name
116
117           c. Parses the document
118
119           d. Reads and applies all the addenda specified
120
121           e. Writes the translated document to file_out_name (if given)
122
123           f. Writes the extracted PO file to po_out_name (if given)
124
125           ARGUMENTS, beside the ones accepted by new() (with expected type):
126
127           file_in_name (@)
128               List of filenames where we should read the input document.
129
130           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
134           file_out_name ($)
135               Filename where we should write the output document.
136
137           file_out_charset ($)
138               Charset used in the output document (if it isn't specified, it
139               will use the PO file charset).
140
141           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
146           po_out_name ($)
147               Filename where we should write the output PO file, containing
148               the strings extracted from the input document.
149
150           addendum (@)
151               List of filenames where we should read the addenda from.
152
153           addendum_charset ($)
154               Charset for the addenda.
155
156       new(%)
157           Create a new po4a document. Accepted options (but be in a hash):
158
159           verbose ($)
160               Sets the verbosity.
161
162           debug ($)
163               Sets the debugging.
164
165   Manipulating document files
166       read($$)
167           Add another input document data at the end of the existing array
168           "@{$self->{TT}{doc_in}}". The argument is the filename to read. If
169           a second argument is provided, it is the filename to use in the
170           references.
171
172           This array "@{$self->{TT}{doc_in}}" holds this input document data
173           as an array of strings with alternating meanings.
174            * The string $textline holding each line of the input text data.
175            * The string "$filename:$linenum" holding its location and called
176           as
177              "reference" ("linenum" starts with 1).
178
179           Please note that it does not parse anything. You should use the
180           parse() function when you're done with packing input files into the
181           document.
182
183       write($)
184           Write the translated document to the given filename.
185
186           This translated document data are provided by:
187            * "$self->docheader()" holding the header text for the plugin, and
188            * "@{$self->{TT}{doc_out}}" holding each line of the main
189           translated text in the array.
190
191   Manipulating PO files
192       readpo($)
193           Add the content of a file (which name is passed as argument) to the
194           existing input PO. The old content is not discarded.
195
196       writepo($)
197           Write the extracted PO file to the given filename.
198
199       stats()
200           Returns some statistics about the translation done so far. Please
201           note that it's not the same statistics than the one printed by
202           msgfmt --statistic. Here, it's stats about recent usage of the PO
203           file, while msgfmt reports the status of the file. It is a wrapper
204           to the Locale::Po4a::Po::stats_get function applied to the input PO
205           file. Example of use:
206
207               [normal use of the po4a document...]
208
209               ($percent,$hit,$queries) = $document->stats();
210               print "We found translations for $percent\%  ($hit from $queries) of strings.\n";
211
212       is_po_uptodate()
213           Returns ($uptodate, $diagnostic) where $uptodate is whether the
214           input po and the output po match (if not, it means that the input
215           po should be updated) and $diagnostic is a string explaining why
216           the po file is not uptodate, when this happens.
217
218   Manipulating addenda
219       addendum($)
220           Please refer to po4a(7) for more information on what addenda are,
221           and how translators should write them. To apply an addendum to the
222           translated document, simply pass its filename to this function and
223           you are done ;)
224
225           This function returns a non-null integer on error.
226

INTERNAL FUNCTIONS used to write derivative parsers

228   Getting input, providing output
229       Four functions are provided to get input and return output. They are
230       very similar to shift/unshift and push/pop of Perl.
231
232        * Perl shift returns the first array item and drop it from the array.
233        * Perl unshift prepends an item to the array as the first array item.
234        * Perl pop returns the last array item and drop it from the array.
235        * Perl push appends an item to the array as the last array item.
236
237       The first pair is about input, while the second is about output.
238       Mnemonic: in input, you are interested in the first line, what shift
239       gives, and in output you want to add your result at the end, like push
240       does.
241
242       shiftline()
243           This function returns the first line to be parsed and its
244           corresponding reference (packed as an array) from the array
245           "@{$self->{TT}{doc_in}}" and drop these first 2 array items.  Here,
246           the reference is provided by a string "$filename:$linenum".
247
248       unshiftline($$)
249           Unshifts the last shifted line of the input document and its
250           corresponding reference back to the head of
251           "{$self->{TT}{doc_in}}".
252
253       pushline($)
254           Push a new line to the end of "{$self->{TT}{doc_out}}".
255
256       popline()
257           Pop the last pushed line from the end of "{$self->{TT}{doc_out}}".
258
259   Marking strings as translatable
260       One function is provided to handle the text which should be translated.
261
262       translate($$$)
263           Mandatory arguments:
264
265           - A string to translate
266
267           - The reference of this string (i.e. position in inputfile)
268
269           - The type of this string (i.e. the textual description of its
270             structural role; used in Locale::Po4a::Po::gettextization(); see
271             also po4a(7), section Gettextization: how does it work?)
272
273           This function can also take some extra arguments. They must be
274           organized as a hash. For example:
275
276             $self->translate("string","ref","type",
277                              'wrap' => 1);
278
279           wrap
280               boolean indicating whether we can consider that whitespaces in
281               string are not important. If yes, the function canonizes the
282               string before looking for a translation or extracting it, and
283               wraps the translation.
284
285           wrapcol
286               the column at which we should wrap (default: 76).
287
288           comment
289               an extra comment to add to the entry.
290
291           Actions:
292
293           - Pushes the string, reference and type to po_out.
294
295           - Returns the translation of the string (as found in po_in) so that
296             the parser can build the doc_out.
297
298           - Handles the charsets to recode the strings before sending them to
299             po_out and before returning the translations.
300
301   Misc functions
302       verbose()
303           Returns if the verbose option was passed during the creation of the
304           TransTractor.
305
306       debug()
307           Returns if the debug option was passed during the creation of the
308           TransTractor.
309
310       detected_charset($)
311           This tells TransTractor that a new charset (the first argument) has
312           been detected from the input document. It can usually be read from
313           the document header. Only the first charset will remain, coming
314           either from the process() arguments or detected from the document.
315
316       get_out_charset()
317           This function will return the charset that should be used in the
318           output document (usually useful to substitute the input document's
319           detected charset where it has been found).
320
321           It will use the output charset specified in the command line. If it
322           wasn't specified, it will use the input PO's charset, and if the
323           input PO has the default "CHARSET", it will return the input
324           document's charset, so that no encoding is performed.
325
326       recode_skipped_text($)
327           This function returns the recoded text passed as argument, from the
328           input document's charset to the output document's one. This isn't
329           needed when translating a string (translate() recodes everything
330           itself), but it is when you skip a string from the input document
331           and you want the output document to be consistent with the global
332           encoding.
333

FUTURE DIRECTIONS

335       One shortcoming of the current TransTractor is that it can't handle
336       translated document containing all languages, like debconf templates,
337       or .desktop files.
338
339       To address this problem, the only interface changes needed are:
340
341       - take a hash as po_in_name (a list per language)
342
343       - add an argument to translate to indicate the target language
344
345       - make a pushline_all function, which would make pushline of its
346         content for all languages, using a map-like syntax:
347
348             $self->pushline_all({ "Description[".$langcode."]=".
349                                   $self->translate($line,$ref,$langcode)
350                                 });
351
352       Will see if it's enough ;)
353

AUTHORS

355        Denis Barbier <barbier@linuxfr.org>
356        Martin Quinson (mquinson#debian.org)
357        Jordi Vilalta <jvprat@gmail.com>
358
359
360
361Po4a Tools                        2021-11-01   Locale::Po4a::TransTractor(3pm)
Impressum