## TranslateService

TranslateService — service object

## Synopsis

    struct      TranslateService;
    struct      TranslateServiceClass;
    const char* translate_service_get_name      (TranslateService *service);
    const char* translate_service_get_nick      (TranslateService *service);
    unsigned int translate_service_get_max_chunk_len
                                                (TranslateService *service);
    const GSList* translate_service_get_pairs   (TranslateService *service);

## Object Hierarchy

      GObject
       +----TranslateService

## Properties

      "max-chunk-len"        guint                : Read / Write / Construct Only
      "name"                 gchararray           : Read / Write / Construct Only
      "nick"                 gchararray           : Read / Write / Construct Only
      "pairs"                gpointer             : Read

## Description

A TranslateService object defines a set of language pairs as well as the methods to translate a text or web page using one of the pairs.

A new translation service can be implemented in two ways:

Adding a definition to the `services.xml` file

The generic module provides an abstract framework for supporting web-based translation services. At runtime, the generic module reads service definitions from `services.xml` files and creates the services defined in these files.

If you are adding support for a web-based translation service, this is the way to go. See the services.xml(5) manual page for more details.

Creating a TranslateService subclass

If the `services.xml` file cannot satisfactorily be used to describe the service you want to implement, you need to program the service in C by creating a subclass of TranslateService and overriding the `get_pairs`, `translate_text` and/or `translate_web_page` methods.

If you want all the applications using libtranslate to be able to use the new service, you need to create a libtranslate module and install it in the appropriate path (see Compiling libtranslate Modules). Otherwise, just integrate the service with your application. In either case, you need to expose an instance of the service to libtranslate by calling `translate_add_service()`. If the service is included in a module, this needs to be done from `translate_module_init()`. Otherwise, do it from your application initialization code, somewhere after the call to `translate_init()`.

## Details

### struct TranslateService

    struct TranslateService;

The TranslateService struct contains private data only, and should be accessed using the functions below.

### struct TranslateServiceClass

    struct TranslateServiceClass {

      GObjectClass		parent;

      gboolean	 (*get_pairs)		(TranslateService	 *service,
    					 GSList			**pairs,
    					 TranslateProgressFunc	  progress_func,
    					 gpointer		  user_data,
    					 GError			**err);
      char		*(*translate_text)	(TranslateService	 *service,
    					 const char		 *text,
    					 const char		 *from,
    					 const char		 *to,
    					 TranslateProgressFunc	  progress_func,
    					 gpointer		  user_data,
    					 GError			**err);
      char		*(*translate_web_page)	(TranslateService	 *service,
    					 const char		 *url,
    					 const char		 *from,
    					 const char		 *to,
    					 TranslateProgressFunc	  progress_func,
    					 gpointer		  user_data,
    					 GError			**err);

    };

The service class contains methods which should be implemented by subclasses in order to provide the service functionality.

Implementing the `get_pairs` method is mandatory. The `translate_text` and `translate_web_page` methods are only required if any pair returned by the `get_pairs` method has the TRANSLATE_PAIR_TEXT or TRANSLATE_PAIR_WEB_PAGE flag set, respectively.

GObjectClass `parent` | the parent class

gboolean (*`get_pairs`) (TranslateService *service, GSList **pairs, TranslateProgressFunc progress_func, gpointer user_data, GError **err)

Specifies the function which is called to retrieve the list of language pairs implemented by `service`. The function should return `TRUE` and store a list of TranslatePair objects in `pairs` on success, or return `FALSE` and store an error in `err` on failure. If `progress_func` is not `NULL`, `get_pairs` should call it at regular intervals with a progress update (or -1 if the progress is unknown), and the `user_data` argument. If, when called, `progress_func` returns `FALSE`, `get_pairs` must cancel the operation as soon as possible, return `NULL`, and set `err` to an error of domain TRANSLATE_ERROR and code TRANSLATE_ERROR_CANCELLED.

char* (*`translate_text`) (TranslateService *service, const char *text, const char *from, const char *to, TranslateProgressFunc progress_func, gpointer user_data, GError **err)

Specifies the function which is called to translate a chunk of text. The function should return a newly-allocated string containing the translation of `text` on success, or return `NULL` and set `err` on failure. If the max-chunk-len property of service is not 0, it is guaranteed that the number of UTF-8 characters in `text` will not exceed max-chunk-len . It is guaranteed that the `from`/`to` pair will be a member (with the flag TRANSLATE_PAIR_TEXT set) of the list returned by the `get_pairs` method. If `progress_func` is not `NULL`, `translate_text` should call it at regular intervals with a progress update (or -1 if the progress is unknown), and the `user_data` argument. If, when called, `progress_func` returns `FALSE`, `translate_text` must cancel the translation as soon as possible, return `NULL`, and set `err` to an error of domain TRANSLATE_ERROR and code TRANSLATE_ERROR_CANCELLED.

char* (*`translate_web_page`) (TranslateService *service, const char *url, const char *from, const char *to, TranslateProgressFunc progress_func, gpointer user_data, GError **err)

Specifies the function which is called to translate a web page. The function should return a newly-allocated string containing the URL of the translated web page on success, or return `NULL` and set `err` on failure. It is guaranteed that the `from`/`to` pair will be a member (with the flag TRANSLATE_PAIR_WEB_PAGE set) of the list returned by the `get_pairs` method. If `progress_func` is not `NULL`, `translate_web_page` should call it at regular intervals with a progress update (or -1 if the progress is unknown), and the `user_data` argument. If, when called, `progress_func` returns `FALSE`, `translate_web_page` must cancel the translation as soon as possible, return `NULL`, and set `err` to an error of domain TRANSLATE_ERROR and code TRANSLATE_ERROR_CANCELLED.

### translate_service_get_name ()

    const char* translate_service_get_name      (TranslateService *service);

Gets the symbolic name of `service`.

`service` : | a service.
Returns : | the symbolic name of `service`, encoded in ASCII.

### translate_service_get_nick ()

    const char* translate_service_get_nick      (TranslateService *service);

Gets the human-readable name of `service`.

`service` : | a service.
Returns : | the human-readable name of `service`.

### translate_service_get_max_chunk_len ()

    unsigned int translate_service_get_max_chunk_len
                                                (TranslateService *service);

Gets the maximum chunk length of `service`.

`service` : | a service.
Returns : | the maximum chunk length of `service`, in characters.

### translate_service_get_pairs ()

    const GSList* translate_service_get_pairs   (TranslateService *service);

Gets the list of language pairs implemented by `service`.

`service` : | a service.
Returns : | a list of TranslatePair objects.

## Properties

"`max-chunk-len`" (guint : Read / Write / Construct Only) | The maximum length of an input chunk, in characters (0 means unlimited).
"`name`" (gchararray : Read / Write / Construct Only) | The service symbolic name, encoded in ASCII.
"`nick`" (gchararray : Read / Write / Construct Only) | The service human-readable name.
"`pairs`" (gpointer : Read) | The list of language pairs this service implements.