NAME
services.xml - libtranslate generic service definitions
DESCRIPTION
The services.xml file contains translation service definitions for the
libtranslate generic module.
The generic module provides an abstract framework for supporting
web-based translation services.
When the generic module is initialized, it reads service definitions
from the services.xml files located in /usr/share/libtranslate and
~/.libtranslate, creates the services defined in these files, and makes
them available to libtranslate.
The services.xml file must be encoded in UTF-8, and conform to the
services.xml Document Type Definition, located in
/usr/share/libtranslate/services.dtd.
ELEMENTS
services
Description
The services element is the root of the document, and may
contains service definitions and language mappings.
Children
These elements may occur zero or more times in services:
custom-language, service.
custom-language
Description
The custom-language element maps a RFC 3066 language tag to a
language name.
Note
Some RFC 3066 tag to name mappings are built into libtranslate
and do not need to be added (see the Built-In RFC 3066 Tag to
Name Mappings appendix in the libtranslate Reference Manual).
Attributes
tag (required)
The RFC 3066 language tag.
name (required)
The language human-readable name.
Parents
This element contains custom-language: services.
service
Description
The service element defines a translation service.
Attributes
name (required)
The service symbolic name, encoded in ASCII.
nick (implied, default: name)
The service human-readable name.
max-chunk-len (optional, default: 1000)
The maximum length of an input chunk, in characters (0
means unlimited).
Parents
This element contains service: services.
Children
This element may occur zero or more times in service: group.
group
Description
The group element defines a translation group (a group
represents a set of languages and translation methods).
Parents
This element contains group: service.
Children
These elements may occur zero or more times in group: language,
http-header.
These elements may occur zero or one time in group:
text-translation, web-page-translation.
language
Description
The language element adds a language to the list of languages
supported by a group.
Attributes
tag (required)
The RFC 3066 language tag.
service-tag (implied, default: tag)
The language service-specific tag. This tag is not
exposed to libtranslate, but is available as from and to
variables (see Variable Substitution).
to (optional, default: none)
A comma-separated list of RFC 3066 language tags this
language can be translated into. The special list element
* means "every language of this group but this one".
Parents
This element contains language: group.
http-header
Description
The http-header element adds a HTTP header to the list of
headers that are set when a HTTP request is issued.
If the http-header element occurs inside a group element, the
header is added for text and web page translations.
If it occurs inside a text-translation or web-page-translation
element, the header is only added for a text or web page
translation, respectively.
Attributes
name (required)
The HTTP header name.
value (required)
The HTTP header value.
Parents
These elements contain http-header: group, text-translation,
web-page-translation.
text-translation
Description
The presence of the text-translation element specifies that the
group can translate text.
Attributes
url (required)
The URL to use for translating text. Variable
substitution is performed on the URL (see Variable
Substitution).
post (optional, default: none)
If this attribute is present, a HTTP POST request is
issued (using the attribute value as post data).
Otherwise, a HTTP GET request is issued. Variable
substitution is performed on the post data (see Variable
Substitution).
Parents
This element contains text-translation: group.
Children
These element may occur zero or more times in text-translation:
http-header, pre-marker, error-marker.
This element may occur zero or one time in text-translation:
post-marker.
pre-marker
Description
The pre-marker element is used to extract the translated text
from the response to a text translation request.
For each pre-marker element, the parser locates text in the
server response. If text is found, the parser moves to the
character following text. If it is not found, the translation
fails. The translated text starts at the character following the
last pre-marker match. If no pre-marker element is specified,
the translated text starts at the first character of the server
response.
Attributes
text (required)
The text to match.
Parents
This element contains pre-marker: text-translation.
post-marker
Description
The post-marker element is used to extract the translated text
from the response to a text translation request.
If text can be located in the server response, the translated
text ends at the character preceding text. Otherwise, the
translation fails. If no post-marker element is specified, the
translated text ends at the last character of the server
response.
Attributes
text (required)
The text to match.
Parents
This element contains post-marker: text-translation.
error-marker
Description
The error-marker element is used to check if a text translation
error has occurred.
If one or more error-marker elements are specified and the text
of any of them can be located anywhere in the server response,
the translation fails.
Attributes
text (required)
The text to match.
Parents
This element contains error-marker: text-translation.
web-page-translation
Description
The presence of the web-page-translation element specifies that
the group can translate a web page.
If no http-header element is specified and if post is not
specified, the generic module does not need to connect to the
server. In this case, url is returned as the URL of the
translated web page. Otherwise, the generic module connects to
the server, issues a HTTP GET or POST request, saves the
response to a local file, and returns a file:// URL pointing to
that file.
Attributes
url (required)
The URL to use for translating a web page. Variable
substitution is performed on the URL (see Variable
Substitution).
post (optional, default: none)
If this attribute is present, a HTTP POST request is
issued (using the attribute value as post data).
Otherwise, a HTTP GET request is issued (or no request at
all, see above). Variable substitution is performed on
the post data (see Variable Substitution).
Parents
This element contains web-page-translation: group.
Children
This element may occur zero or more times in
web-page-translation: http-header.
VARIABLE SUBSTITUTION
Variable substitution is performed at translation time on the url and
post attributes of the text-translation and web-page-translation
elements.
A variable has the syntax ${varname[:modifiers]}.
varname may be any of the following variables:
text (text-translation only)
The text to translate.
url (web-page-translation only)
The URL of the web page to translate.
from The source language service tag.
to The destination language service tag.
time The number of seconds since 0 hours, 0 minutes, 0 seconds,
January 1, 1970, Coordinated Universal Time.
modifiers is a comma-separated list of modifiers. Each modifier is
applied (in the specified order) on the contents of the variable. A
modifier has the syntax name[=value].
name may be any of the following modifiers:
escape Escapes the unsafe characters in the variable using URI percent
notation.
charset
Converts the variable from UTF-8 (the libtranslate character
set) to the character set value.
FILES
/usr/share/libtranslate/services.xml
The system-wide service definitions.
~/.libtranslate/services.xml
The user service definitions.
/usr/share/libtranslate/services.dtd
The services.xml Document Type Definition.
SEE ALSO
The libtranslate Reference Manual
AUTHOR
Jean-Yves Lefort.