services.xml

5

# services.xml Manual

services.xml

libtranslate generic service definitions

## Description

The &file; 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 &file; files located in `@pkgdatadir@` and `~/.libtranslate`, creates the services defined in these files, and makes them available to libtranslate.

The &file; file must be encoded in UTF-8, and conform to the &file; Document Type Definition, located in `@pkgdatadir@/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.

  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

`@pkgdatadir@/services.xml`

The system-wide service definitions.

`~/.libtranslate/services.xml`

The user service definitions.

`@pkgdatadir@/services.dtd`

The &file; Document Type Definition.

## See Also

The libtranslate Reference Manual