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 parentthe 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.