Provided by: libtranslate0_0.99-0ubuntu6_i386 bug

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.