1Locale::Po4a::Xml(3pm) Po4a Tools Locale::Po4a::Xml(3pm)
2
6 Locale::Po4a::Xml - convert XML documents and derivates from/to PO
7 files
8
10 The po4a (PO for anything) project goal is to ease translations (and
11 more interestingly, the maintenance of translations) using gettext
12 tools on areas where they were not expected like documentation.
13 Locale::Po4a::Xml is a module to help the translation of XML documents
15 into other [human] languages. It can also be used as a base to build
16 modules for XML-based documents.
17
19 This module can be used directly to handle generic XML documents. This
20 will extract all tag's content, and no attributes, since it's where the
21 text is written in most XML based documents.
22 There are some options (described in the next section) that can
24 customize this behavior. If this doesn't fit to your document format
25 you're encouraged to write your own module derived from this, to
26 describe your format's details. See the section WRITING DERIVATE
27 MODULES below, for the process description.
28
30 The global debug option causes this module to show the excluded
31 strings, in order to see if it skips something important.
32 These are this module's particular options:
34 nostrip
36 Prevents it to strip the spaces around the extracted strings.
37 wrap
39 Canonicalizes the string to translate, considering that whitespaces
40 are not important, and wraps the translated document. This option
41 can be overridden by custom tag options. See the "tags" option
42 below.
43 unwrap_attributes
45 Attributes are wrapped by default. This option disables wrapping.
46 caseinsensitive
48 It makes the tags and attributes searching to work in a case
49 insensitive way. If it's defined, it will treat <BooK>laNG and
50 <BOOK>Lang as <book>lang.
51 escapequotes
53 Escape quotes in output strings. Necessary, for example, for
54 creating string resources for use by Android build tools.
55 See also:
57 https://developer.android.com/guide/topics/resources/string-resource.html
58 includeexternal
60 When defined, external entities are included in the generated
61 (translated) document, and for the extraction of strings. If it's
62 not defined, you will have to translate external entities
63 separately as independent documents.
64 ontagerror
66 This option defines the behavior of the module when it encounters
67 invalid XML syntax (a closing tag which does not match the last
68 opening tag, or a tag's attribute without value). It can take the
69 following values:
70 fail
72 This is the default value. The module will exit with an error.
73 warn
75 The module will continue, and will issue a warning.
76 silent
78 The module will continue without any warnings.
79 Be careful when using this option. It is generally recommended to
81 fix the input file.
82 tagsonly
84 Extracts only the specified tags in the "tags" option. Otherwise,
85 it will extract all the tags except the ones specified.
86 Note: This option is deprecated.
88 doctype
90 String that will try to match with the first line of the document's
91 doctype (if defined). If it doesn't, a warning will indicate that
92 the document might be of a bad type.
93 addlang
95 String indicating the path (e.g. <bbb><aaa>) of a tag where a
96 lang="..." attribute shall be added. The language will be defined
97 as the basename of the PO file without any .po extension.
98 tags
100 Space-separated list of tags you want to translate or skip. By
101 default, the specified tags will be excluded, but if you use the
102 "tagsonly" option, the specified tags will be the only ones
103 included. The tags must be in the form <aaa>, but you can join
104 some (<bbb><aaa>) to say that the content of the tag <aaa> will
105 only be translated when it's into a <bbb> tag.
106 You can also specify some tag options by putting some characters in
108 front of the tag hierarchy. For example, you can put 'w' (wrap) or
109 'W' (don't wrap) to override the default behavior specified by the
110 global "wrap" option.
111 Example: W<chapter><title>
113 Note: This option is deprecated. You should use the translated and
115 untranslated options instead.
116 attributes
118 Space-separated list of tag's attributes you want to translate.
119 You can specify the attributes by their name (for example, "lang"),
120 but you can prefix it with a tag hierarchy, to specify that this
121 attribute will only be translated when it's in the specified tag.
122 For example: <bbb><aaa>lang specifies that the lang attribute will
123 only be translated if it's in an <aaa> tag, and it's in a <bbb>
124 tag.
125 foldattributes
127 Do not translate attributes in inline tags. Instead, replace all
128 attributes of a tag by po4a-id=<id>.
129 This is useful when attributes shall not be translated, as this
131 simplifies the strings for translators, and avoids typos.
132 customtag
134 Space-separated list of tags which should not be treated as tags.
135 These tags are treated as inline, and do not need to be closed.
136 break
138 Space-separated list of tags which should break the sequence. By
139 default, all tags break the sequence.
140 The tags must be in the form <aaa>, but you can join some
142 (<bbb><aaa>), if a tag (<aaa>) should only be considered when it's
143 within another tag (<bbb>).
144 inline
146 Space-separated list of tags which should be treated as inline. By
147 default, all tags break the sequence.
148 The tags must be in the form <aaa>, but you can join some
150 (<bbb><aaa>), if a tag (<aaa>) should only be considered when it's
151 within another tag (<bbb>).
152 placeholder
154 Space-separated list of tags which should be treated as
155 placeholders. Placeholders do not break the sequence, but the
156 content of placeholders is translated separately.
157 The location of the placeholder in its block will be marked with a
159 string similar to:
160 <placeholder type=\"footnote\" id=\"0\"/>
162 The tags must be in the form <aaa>, but you can join some
164 (<bbb><aaa>), if a tag (<aaa>) should only be considered when it's
165 within another tag (<bbb>).
166 nodefault
168 Space separated list of tags that the module should not try to set
169 by default in any category.
170 cpp Support C preprocessor directives. When this option is set, po4a
172 will consider preprocessor directives as paragraph separators.
173 This is important if the XML file must be preprocessed because
174 otherwise the directives may be inserted in the middle of lines if
175 po4a consider it belong to the current paragraph, and they won't be
176 recognized by the preprocessor. Note: the preprocessor directives
177 must only appear between tags (they must not break a tag).
178 translated
180 Space-separated list of tags you want to translate.
181 The tags must be in the form <aaa>, but you can join some
183 (<bbb><aaa>), if a tag (<aaa>) should only be considered when it's
184 within another tag (<bbb>).
185 You can also specify some tag options by putting some characters in
187 front of the tag hierarchy. For example, you can put 'w' (wrap) or
188 'W' (don't wrap) to override the default behavior specified by the
189 global "wrap" option.
190 Example: W<chapter><title>
192 untranslated
194 Space-separated list of tags you do not want to translate.
195 The tags must be in the form <aaa>, but you can join some
197 (<bbb><aaa>), if a tag (<aaa>) should only be considered when it's
198 within another tag (<bbb>).
199 defaulttranslateoption
201 The default categories for tags that are not in any of the
202 translated, untranslated, break, inline, or placeholder.
203 This is a set of letters:
205 w Tags should be translated and content can be re-wrapped.
207 W Tags should be translated and content should not be re-wrapped.
209 i Tags should be translated inline.
211 p Tags should be translated as placeholders.
213
215 DEFINE WHAT TAGS AND ATTRIBUTES TO TRANSLATE
216 The simplest customization is to define which tags and attributes you
217 want the parser to translate. This should be done in the initialize
218 function. First you should call the main initialize, to get the
219 command-line options, and then, append your custom definitions to the
220 options hash. If you want to treat some new options from command line,
221 you should define them before calling the main initialize:
222 $self->{options}{'new_option'}='';
224 $self->SUPER::initialize(%options);
225 $self->{options}{'_default_translated'}.=' <p> <head><title>';
226 $self->{options}{'attributes'}.=' <p>lang id';
227 $self->{options}{'_default_inline'}.=' <br>';
228 $self->treat_options;
229 You should use the _default_inline, _default_break,
231 _default_placeholder, _default_translated, _default_untranslated, and
232 _default_attributes options in derivated modules. This allow users to
233 override the default behavior defined in your module with command line
234 options.
235 OVERRIDING THE found_string FUNCTION
237 Another simple step is to override the function "found_string", which
238 receives the extracted strings from the parser, in order to translate
239 them. There you can control which strings you want to translate, and
240 perform transformations to them before or after the translation itself.
241 It receives the extracted text, the reference on where it was, and a
243 hash that contains extra information to control what strings to
244 translate, how to translate them and to generate the comment.
245 The content of these options depends on the kind of string it is
247 (specified in an entry of this hash):
248 type="tag"
250 The found string is the content of a translatable tag. The entry
251 "tag_options" contains the option characters in front of the tag
252 hierarchy in the module "tags" option.
253 type="attribute"
255 Means that the found string is the value of a translatable
256 attribute. The entry "attribute" has the name of the attribute.
257 It must return the text that will replace the original in the
259 translated document. Here's a basic example of this function:
260 sub found_string {
262 my ($self,$text,$ref,$options)=@_;
263 $text = $self->translate($text,$ref,"type ".$options->{'type'},
264 'wrap'=>$self->{options}{'wrap'});
265 return $text;
266 }
267 There's another simple example in the new Dia module, which only
269 filters some strings.
270 MODIFYING TAG TYPES (TODO)
272 This is a more complex one, but it enables a (almost) total
273 customization. It's based on a list of hashes, each one defining a tag
274 type's behavior. The list should be sorted so that the most general
275 tags are after the most concrete ones (sorted first by the beginning
276 and then by the end keys). To define a tag type you'll have to make a
277 hash with the following keys:
278 beginning
280 Specifies the beginning of the tag, after the "<".
281 end Specifies the end of the tag, before the ">".
283 breaking
285 It says if this is a breaking tag class. A non-breaking (inline)
286 tag is one that can be taken as part of the content of another tag.
287 It can take the values false (0), true (1) or undefined. If you
288 leave this undefined, you'll have to define the f_breaking function
289 that will say whether a concrete tag of this class is a breaking
290 tag or not.
291 f_breaking
293 It's a function that will tell if the next tag is a breaking one or
294 not. It should be defined if the breaking option is not.
295 f_extract
297 If you leave this key undefined, the generic extraction function
298 will have to extract the tag itself. It's useful for tags that can
299 have other tags or special structures in them, so that the main
300 parser doesn't get mad. This function receives a boolean that says
301 if the tag should be removed from the input stream or not.
302 f_translate
304 This function receives the tag (in the get_string_until() format)
305 and returns the translated tag (translated attributes or all needed
306 transformations) as a single string.
307
309 WORKING WITH TAGS
310 get_path()
311 This function returns the path to the current tag from the
312 document's root, in the form <html><body><p>.
313 An additional array of tags (without brackets) can be passed as
315 argument. These path elements are added to the end of the current
316 path.
317 tag_type()
319 This function returns the index from the tag_types list that fits
320 to the next tag in the input stream, or -1 if it's at the end of
321 the input file.
322 extract_tag($$)
324 This function returns the next tag from the input stream without
325 the beginning and end, in an array form, to maintain the references
326 from the input file. It has two parameters: the type of the tag
327 (as returned by tag_type) and a boolean, that indicates if it
328 should be removed from the input stream.
329 get_tag_name(@)
331 This function returns the name of the tag passed as an argument, in
332 the array form returned by extract_tag.
333 breaking_tag()
335 This function returns a boolean that says if the next tag in the
336 input stream is a breaking tag or not (inline tag). It leaves the
337 input stream intact.
338 treat_tag()
340 This function translates the next tag from the input stream. Using
341 each tag type's custom translation functions.
342 tag_in_list($@)
344 This function returns a string value that says if the first
345 argument (a tag hierarchy) matches any of the tags from the second
346 argument (a list of tags or tag hierarchies). If it doesn't match,
347 it returns 0. Else, it returns the matched tag's options (the
348 characters in front of the tag) or 1 (if that tag doesn't have
349 options).
350 WORKING WITH ATTRIBUTES
352 treat_attributes(@)
353 This function handles the translation of the tags' attributes. It
354 receives the tag without the beginning / end marks, and then it
355 finds the attributes, and it translates the translatable ones
356 (specified by the module option "attributes"). This returns a
357 plain string with the translated tag.
358 WORKING WITH THE MODULE OPTIONS
360 treat_options()
361 This function fills the internal structures that contain the tags,
362 attributes and inline data with the options of the module
363 (specified in the command-line or in the initialize function).
364 GETTING TEXT FROM THE INPUT DOCUMENT
366 get_string_until($%)
367 This function returns an array with the lines (and references) from
368 the input document until it finds the first argument. The second
369 argument is an options hash. Value 0 means disabled (the default)
370 and 1, enabled.
371 The valid options are:
373 include
375 This makes the returned array to contain the searched text
376 remove
378 This removes the returned stream from the input
379 unquoted
381 This ensures that the searched text is outside any quotes
382 skip_spaces(\@)
384 This function receives as argument the reference to a paragraph (in
385 the format returned by get_string_until), skips his heading spaces
386 and returns them as a simple string.
387 join_lines(@)
389 This function returns a simple string with the text from the
390 argument array (discarding the references).
391
393 This module can translate tags and attributes.
394
396 DOCTYPE (ENTITIES)
397 There is a minimal support for the translation of entities. They are
399 translated as a whole, and tags are not taken into account. Multilines
400 entities are not supported and entities are always rewrapped during the
401 translation.
402 MODIFY TAG TYPES FROM INHERITED MODULES (move the tag_types structure
404 inside the $self hash?)
405
407 Locale::Po4a::TransTractor(3pm), po4a(7)
408
410 Jordi Vilalta <jvprat@gmail.com>
411 Nicolas François <nicolas.francois@centraliens.net>
412
414 Copyright (c) 2004 by Jordi Vilalta <jvprat@gmail.com>
415 Copyright (c) 2008-2009 by Nicolas François <nicolas.francois@centraliens.net>
416 This program is free software; you may redistribute it and/or modify it
418 under the terms of GPL (see the COPYING file).
419Po4a Tools 2018-09-24 Locale::Po4a::Xml(3pm)