1SERVICES.XML(5)               services.xml Manual              SERVICES.XML(5)
2
3
4

NAME

6       services.xml - libtranslate generic service definitions
7

DESCRIPTION

9       The  services.xml file contains translation service definitions for the
10       libtranslate generic module.
11
12
13       The generic  module  provides  an  abstract  framework  for  supporting
14       web-based translation services.
15
16
17       When  the  generic  module is initialized, it reads service definitions
18       from the services.xml  files  located  in  /usr/share/libtranslate  and
19       ~/.libtranslate, creates the services defined in these files, and makes
20       them available to libtranslate.
21
22
23       The services.xml file must be encoded in UTF-8, and conform to the ser‐
24       vices.xml  Document  Type  Definition,  located in /usr/share/libtrans‐
25       late/services.dtd.
26
27

ELEMENTS

29   services
30       Description
31              The services element is the root of the document, and  may  con‐
32              tains service definitions and language mappings.
33
34
35       Children
36              These  elements  may  occur zero or more times in services: cus‐
37              tom-language, service.
38
39
40   custom-language
41       Description
42              The custom-language element maps a RFC 3066 language  tag  to  a
43              language name.
44
45
46              Note
47
48              Some  RFC  3066 tag to name mappings are built into libtranslate
49              and do not need to be added (see the Built-In RFC  3066  Tag  to
50              Name Mappings appendix in the libtranslate Reference Manual).
51
52
53
54       Attributes
55
56
57
58              tag (required)
59                     The RFC 3066 language tag.
60
61
62              name (required)
63                     The language human-readable name.
64
65
66       Parents
67              This element contains custom-language: services.
68
69
70   service
71       Description
72              The service element defines a translation service.
73
74
75       Attributes
76
77
78
79              name (required)
80                     The service symbolic name, encoded in ASCII.
81
82
83              nick (implied, default: name)
84                     The service human-readable name.
85
86
87              max-chunk-len (optional, default: 1000)
88                     The  maximum  length  of an input chunk, in characters (0
89                     means unlimited).
90
91
92       Parents
93              This element contains service: services.
94
95
96       Children
97              This element may occur zero or more times in service: group.
98
99
100   group
101       Description
102              The group element defines a translation group  (a  group  repre‐
103              sents a set of languages and translation methods).
104
105
106       Parents
107              This element contains group: service.
108
109
110       Children
111              These  elements may occur zero or more times in group: language,
112              http-header.
113
114              These elements may occur zero or one time in group:  text-trans‐
115              lation, web-page-translation.
116
117
118   language
119       Description
120              The  language  element  adds a language to the list of languages
121              supported by a group.
122
123
124       Attributes
125
126
127
128              tag (required)
129                     The RFC 3066 language tag.
130
131
132              service-tag (implied, default: tag)
133                     The  language  service-specific  tag.  This  tag  is  not
134                     exposed  to libtranslate, but is available as from and to
135                     variables (see Variable Substitution).
136
137
138              to (optional, default: none)
139                     A comma-separated list of RFC  3066  language  tags  this
140                     language can be translated into. The special list element
141                     * means "every language of this group but this one".
142
143
144       Parents
145              This element contains language: group.
146
147
148   http-header
149       Description
150              The http-header element adds a HTTP header to the list of  head‐
151              ers that are set when a HTTP request is issued.
152
153              If  the  http-header  element occurs inside a group element, the
154              header is added for text and web page translations.
155
156              If it occurs inside a text-translation  or  web-page-translation
157              element,  the header is only added for a text or web page trans‐
158              lation, respectively.
159
160
161       Attributes
162
163
164
165              name (required)
166                     The HTTP header name.
167
168
169              value (required)
170                     The HTTP header value.
171
172
173       Parents
174              These elements  contain  http-header:  group,  text-translation,
175              web-page-translation.
176
177
178   text-translation
179       Description
180              The  presence of the text-translation element specifies that the
181              group can translate text.
182
183
184       Attributes
185
186
187
188              url (required)
189                     The URL to use for translating text.  Variable  substitu‐
190                     tion is performed on the URL (see Variable Substitution).
191
192
193              post (optional, default: none)
194                     If  this  attribute  is  present,  a HTTP POST request is
195                     issued (using the attribute value as post  data).  Other‐
196                     wise, a HTTP GET request is issued. Variable substitution
197                     is performed on the post  data  (see  Variable  Substitu‐
198                     tion).
199
200
201       Parents
202              This element contains text-translation: group.
203
204
205       Children
206              These  element may occur zero or more times in text-translation:
207              http-header, pre-marker, error-marker.
208
209              This element may occur zero or  one  time  in  text-translation:
210              post-marker.
211
212
213   pre-marker
214       Description
215              The  pre-marker  element  is used to extract the translated text
216              from the response to a text translation request.
217
218              For each pre-marker element, the  parser  locates  text  in  the
219              server response. If text is found, the parser moves to the char‐
220              acter following text. If it is not found, the translation fails.
221              The  translated  text starts at the character following the last
222              pre-marker match. If no pre-marker  element  is  specified,  the
223              translated  text  starts  at  the  first character of the server
224              response.
225
226
227       Attributes
228
229
230
231              text (required)
232                     The text to match.
233
234
235       Parents
236              This element contains pre-marker: text-translation.
237
238
239   post-marker
240       Description
241              The post-marker element is used to extract the  translated  text
242              from the response to a text translation request.
243
244              If  text  can  be located in the server response, the translated
245              text ends at the character preceding text. Otherwise, the trans‐
246              lation fails. If no post-marker element is specified, the trans‐
247              lated text ends at the last character of the server response.
248
249
250       Attributes
251
252
253
254              text (required)
255                     The text to match.
256
257
258       Parents
259              This element contains post-marker: text-translation.
260
261
262   error-marker
263       Description
264              The error-marker element is used to check if a text  translation
265              error has occurred.
266
267              If  one or more error-marker elements are specified and the text
268              of any of them can be located anywhere in the  server  response,
269              the translation fails.
270
271
272       Attributes
273
274
275
276              text (required)
277                     The text to match.
278
279
280       Parents
281              This element contains error-marker: text-translation.
282
283
284   web-page-translation
285       Description
286              The  presence of the web-page-translation element specifies that
287              the group can translate a web page.
288
289              If no http-header element is specified and if post is not speci‐
290              fied, the generic module does not need to connect to the server.
291              In this case, url is returned as the URL of the  translated  web
292              page.  Otherwise,  the  generic  module  connects to the server,
293              issues a HTTP GET or POST request, saves the response to a local
294              file, and returns a file:// URL pointing to that file.
295
296
297       Attributes
298
299
300
301              url (required)
302                     The  URL to use for translating a web page. Variable sub‐
303                     stitution is performed on the URL (see Variable Substitu‐
304                     tion).
305
306
307              post (optional, default: none)
308                     If  this  attribute  is  present,  a HTTP POST request is
309                     issued (using the attribute value as post  data).  Other‐
310                     wise, a HTTP GET request is issued (or no request at all,
311                     see above). Variable substitution  is  performed  on  the
312                     post data (see Variable Substitution).
313
314
315       Parents
316              This element contains web-page-translation: group.
317
318
319       Children
320              This  element  may occur zero or more times in web-page-transla‐
321              tion: http-header.
322
323

VARIABLE SUBSTITUTION

325       Variable substitution is performed at translation time on the  url  and
326       post  attributes  of the text-translation and web-page-translation ele‐
327       ments.
328
329
330       A variable has the syntax ${varname[:modifiers]}.
331
332
333       varname may be any of the following variables:
334
335
336       text (text-translation only)
337              The text to translate.
338
339
340       url (web-page-translation only)
341              The URL of the web page to translate.
342
343
344       from   The source language service tag.
345
346
347       to     The destination language service tag.
348
349
350       time   The number of seconds since 0 hours, 0 minutes, 0 seconds, Janu‐
351              ary 1, 1970, Coordinated Universal Time.
352
353
354       modifiers  is  a  comma-separated  list  of modifiers. Each modifier is
355       applied (in the specified order) on the contents  of  the  variable.  A
356       modifier has the syntax name[=value].
357
358
359       name may be any of the following modifiers:
360
361
362       escape Escapes  the unsafe characters in the variable using URI percent
363              notation.
364
365
366       charset
367              Converts the variable from  UTF-8  (the  libtranslate  character
368              set) to the character set value.
369
370

FILES

372       /usr/share/libtranslate/services.xml
373
374       The system-wide service definitions.
375
376
377       ~/.libtranslate/services.xml
378
379       The user service definitions.
380
381
382       /usr/share/libtranslate/services.dtd
383
384       The services.xml Document Type Definition.
385
386

SEE ALSO

388       The libtranslate Reference Manual
389
390

AUTHOR

392       Jean-Yves Lefort.
393
394
395
396libtranslate 0.99              January 15, 2005                SERVICES.XML(5)
Impressum