<!-- ##### SECTION Title ##### -->
TranslateService

<!-- ##### SECTION Short_Description ##### -->
service object

<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
A new translation service can be implemented in two ways:
</para>
<variablelist>
<varlistentry>
<term>Adding a definition to the <filename>services.xml</filename> file</term>
<listitem>
<para>
The generic module provides an abstract framework for supporting
web-based translation services. At runtime, the generic module reads
service definitions from <filename>services.xml</filename> files and
creates the services defined in these files.
</para>
<para>
If you are adding support for a web-based translation service, this is
the way to go. See the
<citerefentry><refentrytitle>services.xml</refentrytitle><manvolnum>5</manvolnum></citerefentry>
manual page for more details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Creating a #TranslateService subclass</term>
<listitem>
<para>
If the <filename>services.xml</filename> 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.
</para>
<para>
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 <link
linkend="compiling-modules">Compiling libtranslate Modules</link>).
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().
</para>
</listitem>
</varlistentry>
</variablelist>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### STRUCT TranslateService ##### -->
<para>
The #TranslateService struct contains private data only, and should be
accessed using the functions below.
</para>


<!-- ##### ARG TranslateService:max-chunk-len ##### -->
<para>

</para>

<!-- ##### ARG TranslateService:name ##### -->
<para>

</para>

<!-- ##### ARG TranslateService:nick ##### -->
<para>

</para>

<!-- ##### ARG TranslateService:pairs ##### -->
<para>

</para>

<!-- ##### STRUCT TranslateServiceClass ##### -->
<para>
The service class contains methods which should be implemented by
subclasses in order to provide the service functionality.
</para>
<para>
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.
</para>

@parent: the parent class
@get_pairs: 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.
@translate_text: 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 <link
linkend="TranslateService--max-chunk-len">max-chunk-len</link>
property of service is not 0, it is guaranteed that the number of
UTF-8 characters in @text will not exceed <link
linkend="TranslateService--max-chunk-len">max-chunk-len</link> . 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.
@translate_web_page: 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.

<!-- ##### FUNCTION translate_service_get_name ##### -->
<para>

</para>

@service: 
@Returns: 


<!-- ##### FUNCTION translate_service_get_nick ##### -->
<para>

</para>

@service: 
@Returns: 


<!-- ##### FUNCTION translate_service_get_max_chunk_len ##### -->
<para>

</para>

@service: 
@Returns: 


<!-- ##### FUNCTION translate_service_get_pairs ##### -->
<para>

</para>

@service: 
@Returns: 


