1Locale::Po4a::TransTracUtsoerr(3C)ontributed Perl DocumeLnotcaatlieo:n:Po4a::TransTractor(3)
2
6 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 parsers used to parse a docu‐
14 ment to search translatable strings, extract them to a po file and
15 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 docu‐
44 ments, the generation of output, and the extraction of the trans‐
45 latable strings. This is pretty simple using the provided functions
46 presented in the section "INTERNAL FUNCTIONS" below. See also the
47 synopsis, which present an example.
48 This function is called by the process() function bellow, but if
50 you choose to use the new() function, and to add content manually
51 to your document, you will have to call this function yourself.
52 docheader()
54 This function returns the header we should add to the produced doc‐
55 ument, quoted properly to be a comment in the target language. See
56 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 format‐
62 ted, i.e. that '<p>' tags are the only tags present, and that this tag
63 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 . $document->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(%)
111 This function can do all you need to do with a po4a document in one
112 invocation. Its arguments must be packed as a hash. ACTIONS:
113 a. Reads all the po files specified in po_in_name
115 b. Reads all original documents specified in file_in_name
117 c. Parses the document
119 d. Reads and applies all the addenda specified
121 e. Writes the translated document to file_out_name (if given)
123 f. Writes the extracted po file to po_out_name (if given)
125 ARGUMENTS, beside the ones accepted by new() (with expected type):
127 file_in_name (@)
129 List of filenames where we should read the input document.
130 file_in_charset ($)
132 Charset used in the input document (if it isn't specified, it
133 will try to detect it from the input document).
134 file_out_name ($)
136 Filename where we should write the output document.
137 file_out_charset ($)
139 Charset used in the output document (if it isn't specified, it
140 will use the po file charset).
141 po_in_name (@)
143 List of filenames where we should read the input po files from,
144 containing the translation which will be used to translate the
145 document.
146 po_out_name ($)
148 Filename where we should write the output po file, containing
149 the strings extracted from the input document.
150 addendum (@)
152 List of filenames where we should read the addenda from.
153 addendum_charset ($)
155 Charset for the addenda.
156 new(%)
158 Create a new Po4a document. Accepted options (but be in a hash):
159 verbose ($)
161 Sets the verbosity.
162 debug ($)
164 Sets the debugging.
165 Manipulating document files
167 read($)
169 Add another input document at the end of the existing one. The
170 argument is the filename to read.
171 Please note that it does not parse anything. You should use the
173 parse() function when you're done with packing input files into the
174 document.
175 write($)
177 Write the translated document to the given filename.
178 Manipulating po files
180 readpo($)
182 Add the content of a file (which name is passed in argument) to the
183 existing input po. The old content is not discarded.
184 writepo($)
186 Write the extracted po file to the given filename.
187 stats()
189 Returns some statistics about the translation done so far. Please
190 note that it's not the same statistics than the one printed by
191 msgfmt --statistic. Here, it's stats about recent usage of the po
192 file, while msgfmt reports the status of the file. It is a wrapper
193 to the Locale::Po4a::Po::stats_get function applied to the input po
194 file. Example of use:
195 [normal use of the po4a document...]
197 ($percent,$hit,$queries) = $document->stats();
199 print "We found translations for $percent\% ($hit from $queries) of strings.\n";
200 Manipulating addenda
202 addendum($)
204 Please refer to po4a(7) for more information on what addenda are,
205 and how translators should write them. To apply an addendum to the
206 translated document, simply pass its filename to this function and
207 you are done ;)
208 This function returns a non-null integer on error.
210
212 Getting input, providing output
213 Four functions are provided to get input and return output. They are
215 very similar to shift/unshift and push/pop. The first pair is about
216 input, while the second is about output. Mnemonic: in input, you are
217 interested in the first line, what shift gives, and in output you want
218 to add your result at the end, like push does.
219 shiftline()
221 This function returns the next line of the doc_in to be parsed and
222 its reference (packed as an array).
223 unshiftline($$)
225 Unshifts a line of the input document and its reference.
226 pushline($)
228 Push a new line to the doc_out.
229 popline()
231 Pop the last pushed line from the doc_out.
232 Marking strings as translatable
234 One function is provided to handle the text which should be translated.
236 translate($$$)
238 Mandatory arguments:
239 - A string to translate
241 - The reference of this string (ie, position in inputfile)
243 - The type of this string (ie, the textual description of its
245 structural role ; used in Locale::Po4a::Po::gettextization() ;
246 see also po4a(7), section Gettextization: how does it work?)
247 This function can also take some extra arguments. They must be
249 organized as a hash. For example:
250 $self->translate("string","ref","type",
252 'wrap' => 1);
253 wrap
255 boolean indicating whether we can consider that whitespaces in
256 string are not important. If yes, the function canonizes the
257 string before looking for a translation or extracting it, and
258 wraps the translation.
259 wrapcol
261 The column at which we should wrap (default: 76).
262 comment
264 An extra comment to add to the entry.
265 Actions:
267 - Pushes the string, reference and type to po_out.
269 - Returns the translation of the string (as found in po_in) so that
271 the parser can build the doc_out.
272 - Handles the charsets to recode the strings before sending them to
274 po_out and before returning the translations.
275 Misc functions
277 verbose()
279 Returns if the verbose option was passed during the creation of the
280 TransTractor.
281 debug()
283 Returns if the debug option was passed during the creation of the
284 TransTractor.
285 detected_charset($)
287 This tells TransTractor that a new charset (the first argument) has
288 been detected from the input document. It can usually be read from
289 the document header. Only the first charset will remain, coming
290 either from the process() arguments or detected from the document.
291 get_out_charset()
293 This function will return the charset that should be used in the
294 output document (usually useful to substitute the input document's
295 detected charset where it has been found).
296 It will use the output charset specified in the command line. If it
298 wasn't specified, it will use the input po's charset, and if the
299 input po has the default "CHARSET", it will return the input docu‐
300 ment's charset, so that no encoding is performed.
301 recode_skipped_text($)
303 This function returns the recoded text passed as argument, from the
304 input document's charset to the output document's one. This isn't
305 needed when translating a string (translate() recodes everything
306 itself), but it is when you skip a string from the input document
307 and you want the output document to be consistent with the global
308 encoding.
309
311 One shortcoming of the current TransTractor is that it can't handle
312 translated document containing all languages, like debconf templates,
313 or .desktop files.
314 To address this problem, the only interface changes needed are:
316 - take a hash as po_in_name (a list per language)
318 - add an argument to translate to indicate the target language
320 - make a pushline_all function, which would make pushline of its con‐
322 tent for all language, using a map-like syntax:
323 $self->pushline_all({ "Description[".$langcode."]=".
325 $self->translate($line,$ref,$langcode)
326 });
327 Will see if it's enough ;)
329
331 Denis Barbier <barbier@linuxfr.org>
332 Martin Quinson (mquinson#debian.org)
333 Jordi Vilalta <jvprat@gmail.com>
334perl v5.8.8 2008-06-01 Locale::Po4a::TransTractor(3)