## translate

translate — library initialization and core functions

## Synopsis

    #define     TRANSLATE_MAJOR_VERSION
    #define     TRANSLATE_MINOR_VERSION
    #define     TRANSLATE_MICRO_VERSION
    extern      const unsigned int		translate_major_version;
    extern      const unsigned int		translate_minor_version;
    extern      const unsigned int		translate_micro_version;
    #define     TRANSLATE_ERROR
    #define     TRANSLATE_INIT_ERROR
    enum        TranslateError;
    enum        TranslateInitError;
    gboolean    (*TranslateModuleInitFunc)      (GError **err);
    extern      gboolean	   translate_initialized;
    gboolean    translate_init                  (GError **err);
    gboolean    translate_add_service           (TranslateService *service);
    TranslateService* translate_get_service     (const char *name);
    GSList*     translate_get_services          (void);
    gboolean    translate_add_language          (const char *tag,
                                                 const char *name);
    const char* translate_get_language_name     (const char *tag);
    void        translate_set_proxy             (const char *uri);
    char*       translate_get_proxy             (void);

## Description

The following functions, variables and macros are used to determine the libtranslate version, initialize libtranslate, manipulate services, languages and the network proxy.

## Details

### TRANSLATE_MAJOR_VERSION

    #define TRANSLATE_MAJOR_VERSION		0

Like translate_major_version, but from the headers used at application compile time, rather than from the library linked against at application runtime.

### TRANSLATE_MINOR_VERSION

    #define TRANSLATE_MINOR_VERSION		99

Like translate_minor_version, but from the headers used at application compile time, rather than from the library linked against at application runtime.

### TRANSLATE_MICRO_VERSION

    #define TRANSLATE_MICRO_VERSION		0

Like translate_micro_version, but from the headers used at application compile time, rather than from the library linked against at application runtime.

### translate_major_version

    extern const unsigned int		translate_major_version;

The major version number of libtranslate. This variable is in the library, so it represents the translate library you have linked against. Contrast with the TRANSLATE_MAJOR_VERSION macro, which represents the major version of the libtranslate headers you have included.

### translate_minor_version

    extern const unsigned int		translate_minor_version;

The minor version number of libtranslate. This variable is in the library, so it represents the translate library you have linked against. Contrast with the TRANSLATE_MINOR_VERSION macro, which represents the minor version of the libtranslate headers you have included.

### translate_micro_version

    extern const unsigned int		translate_micro_version;

The micro version number of libtranslate. This variable is in the library, so it represents the translate library you have linked against. Contrast with the TRANSLATE_MICRO_VERSION macro, which represents the micro version of the libtranslate headers you have included.

### TRANSLATE_ERROR

    #define TRANSLATE_ERROR			(translate_error_quark())

Generic libtranslate error domain. Errors in this domain are from the TranslateError enumeration.

### TRANSLATE_INIT_ERROR

    #define TRANSLATE_INIT_ERROR		(translate_init_error_quark())

The error domain of `translate_init()`. Errors in this domain are from the TranslateInitError enumeration.

### enum TranslateError

    typedef enum
    {
      TRANSLATE_ERROR_FAILED,
      TRANSLATE_ERROR_CANCELLED
    } TranslateError;

Generic error codes returned by libtranslate routines when more specialized error codes are not relevant.

`TRANSLATE_ERROR_FAILED` | a generic error has occurred
`TRANSLATE_ERROR_CANCELLED` | the user has cancelled the operation

### enum TranslateInitError

    typedef enum
    {
      TRANSLATE_INIT_ERROR_MULTI_THREADING_NOT_SUPPORTED
    } TranslateInitError;

Error codes returned by `translate_init()`.

`TRANSLATE_INIT_ERROR_MULTI_THREADING_NOT_SUPPORTED` | multi-threading is not supported

### TranslateModuleInitFunc ()

    gboolean    (*TranslateModuleInitFunc)      (GError **err);

Specifies the type of the module initialization function.

A libtranslate module must contain a function named `translate_module_init()`, which is called when the module is loaded.

`err` : | a location to report errors, or `NULL`.
Returns : | the function should return `FALSE` if the module could not be initialized. In such case it should also set `err`, which is printed by libtranslate.

### translate_initialized

    extern gboolean	   translate_initialized;

Whether libtranslate is initialized or not (read-only). You probably do not need to use this variable, as `translate_init()` can be called multiple times.

### translate_init ()

    gboolean    translate_init                  (GError **err);

Initializes libtranslate. This function can safely be called multiple times (however, it is not thread-safe, read below). When it is called more than once, it returns the status (and error if any) of the initial invocation.

### Important

Unlike other libtranslate functions, `translate_init()` is not thread-safe, and must not be called while any mutex is held. The reason is that `translate_init()` may call `g_thread_init()`. Refer to the `g_thread_init()` documentation for more details.

`err` : | a location to report errors, or `NULL`. Any of the errors in TranslateInitError or other domains may occur.
Returns : | `TRUE` if the initialization was successful, `FALSE` otherwise (in such case `err` is set to the error that has occurred).

### translate_add_service ()

    gboolean    translate_add_service           (TranslateService *service);

Adds `service` to the libtranslate service list. If a service with the same name is already in the list, nothing is done and `FALSE` is returned.

`service` : | a service.
Returns : | `TRUE` if the service was added, `FALSE` if it was already in the list.

### translate_get_service ()

    TranslateService* translate_get_service     (const char *name);

Looks up a service in the libtranslate service list.

`name` : | a service name, encoded in ASCII.
Returns : | a new reference to the service with name `name`, or `NULL` if not found.

### translate_get_services ()

    GSList*     translate_get_services          (void);

Gets a copy of the libtranslate service list. When no longer needed, the list should be freed with:

    g_slist_foreach(list, (GFunc) g_object_unref, NULL);
    g_slist_free(list);

Returns : | a copy of the libtranslate service list.

### translate_add_language ()

    gboolean    translate_add_language          (const char *tag,
                                                 const char *name);

Adds a language tag to name mapping to the libtranslate language database. If a language with the same tag already exists in the database, nothing is done and `FALSE` is returned.

### Note

Some RFC 3066 tag to name mappings are built into libtranslate and do not need to be added.

`tag` : | a RFC 3066 language tag.
`name` : | the language human-readable name.
Returns : | `TRUE` if the language was added, `FALSE` if it was already in the database.

### translate_get_language_name ()

    const char* translate_get_language_name     (const char *tag);

Looks up a language tag in the libtranslate language database, and returns its human-readable name.

`tag` : | a RFC 3066 language tag.
Returns : | the human-readable name of the language with tag `tag`, or `tag` itself if not found. If the returned string is not `tag`, it is owned by libtranslate and must not be modified or freed.

### translate_set_proxy ()

    void        translate_set_proxy             (const char *uri);

Sets the URI of a proxy server to use for network transfers.

`uri` : | the URI of a proxy server, or `NULL` to unset.

### translate_get_proxy ()

    char*       translate_get_proxy             (void);

Gets the URI thas has been previously set with `translate_set_proxy()`.

If you are implementing a service, you must use this URI for proxying network transfers.

Returns : | the libtranslate proxy URI, or `NULL` if no proxy is set. The returned string should be freed when no longer needed.