## Implementing Translation Services

To implement a translation service, you need to create a subclass of TranslateService, create an instance of your subclass with g_object_new(), and add the service using translate_add_service().

### Web-Based Services

If you are implementing support for a web-based service, just adding a definition to the `services.xml` file (without having to resort to C code) might be sufficient. See the services.xml(5) manual page.

Example 2. A Simple Service for Reversing Text

The following example demonstrates how to create an add-on service for libtranslate, and compile it either as a module or as a standalone application.

The source code of this example is available in the libtranslate source distribution (`docs/reference/example-service.c`), and is reproduced below. To build a module on UNIX, compile the source as follows:

    $ cc `pkg-config --cflags libtranslate` -shared -fPIC example-service.c -o example-service.so

To build a standalone application on UNIX, compile the source as follows:

    $ cc `pkg-config --cflags --libs libtranslate` -DSTANDALONE example-service.c -o example-service

    /*
     * Copyright (C) 2005 Jean-Yves Lefort
     * All rights reserved.
     *
     * Redistribution and use in source and binary forms, with or without
     * modification, are permitted provided that the following conditions
     * are met:
     * 1. Redistributions of source code must retain the above copyright
     *    notice, this list of conditions and the following disclaimer.
     * 2. Redistributions in binary form must reproduce the above copyright
     *    notice, this list of conditions and the following disclaimer in the
     *    documentation and/or other materials provided with the distribution.
     * 3. Neither the name of Jean-Yves Lefort nor the names of its contributors
     *    may be used to endorse or promote products derived from this software
     *    without specific prior written permission.
     *
     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
     * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
     * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
     * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
     * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
     * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
     * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
     * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
     * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     * POSSIBILITY OF SUCH DAMAGE.
     */

    #include <locale.h>
    #include <stdlib.h>
    #include <gmodule.h>
    #include <translate.h>

    #define REVERSE_TYPE_SERVICE		(reverse_service_get_type())

    typedef struct
    {
      TranslateService	parent;
    } ReverseService;

    typedef struct
    {
      TranslateServiceClass	parent;
    } ReverseServiceClass;

    static gboolean
    reverse_service_get_pairs (TranslateService *service,
    			   GSList **pairs,
    			   TranslateProgressFunc progress_func,
    			   gpointer user_data,
    			   GError **err)
    {
      /* initialize the list */
      *pairs = NULL;

      /* add the English -> English (reversed) pair */
      *pairs = g_slist_append(*pairs,
    			  translate_pair_new(TRANSLATE_PAIR_TEXT,
    					     "en", "en-x-rev"));

      /* add the English (reversed) -> English pair */
      *pairs = g_slist_append(*pairs,
    			  translate_pair_new(TRANSLATE_PAIR_TEXT,
    					     "en-x-rev", "en"));

      return TRUE;			/* success */
    }

    static char *
    reverse_service_translate_text (TranslateService *service,
    				const char *text,
    				const char *from,
    				const char *to,
    				TranslateProgressFunc progress_func,
    				gpointer user_data,
    				GError **err)
    {
      return g_utf8_strreverse(text, -1);
    }

    static void
    reverse_service_class_init (ReverseServiceClass *class)
    {
      TranslateServiceClass *service_class = TRANSLATE_SERVICE_CLASS(class);

      service_class->get_pairs = reverse_service_get_pairs;
      service_class->translate_text = reverse_service_translate_text;
    }

    static void
    reverse_service_register_type (GType *type)
    {
      static const GTypeInfo info = {
        sizeof(ReverseServiceClass),
        NULL,
        NULL,
        (GClassInitFunc) reverse_service_class_init,
        NULL,
        NULL,
        sizeof(ReverseService),
        0,
        NULL
      };

      *type = g_type_register_static(TRANSLATE_TYPE_SERVICE,
    				 "ReverseService",
    				 &info,
    				 0);
    }

    static GType
    reverse_service_get_type (void)
    {
      static GType type;
      static GOnce once = G_ONCE_INIT;

      g_once(&once, (GThreadFunc) reverse_service_register_type, &type);

      return type;
    }

    static TranslateService *
    reverse_service_new (void)
    {
      return g_object_new(REVERSE_TYPE_SERVICE,
    		      "name", "reverse",
    		      "nick", "Reverse",
    		      NULL);
    }

    static void
    reverse_service_register_tag (void)
    {
      /*
       * Register our en-x-rev custom tag. The tag name was chosen
       * according to rules specified in RFC 3066 section 2.2.
       *
       * Note that registering a language name is optional and has
       * aesthetical purposes only. If no name exists for a particular
       * tag, the tag itself will be used.
       */
      translate_add_language("en-x-rev", "English (reversed)");
    }

    #ifdef STANDALONE

    int
    main (int argc, char **argv)
    {
      GError *err = NULL;
      GSList *services = NULL;
      TranslateSession *session;
      char *reversed;

      setlocale(LC_ALL, "");	/* use user's locale */

      if (argc != 2)
        {
          g_printerr("Usage: rev TEXT\n");
          exit(1);
        }

      /* initialize libtranslate */
      if (! translate_init(&err))
        {
          g_printerr("Unable to initialize libtranslate: %s\n", err->message);
          g_error_free(err);
          exit(1);
        }

      /* register our custom tag */
      reverse_service_register_tag();

      /* create a session which will use our reverse service */
      services = g_slist_append(services, reverse_service_new());
      session = translate_session_new(services);
      g_slist_foreach(services, (GFunc) g_object_unref, NULL);
      g_slist_free(services);

      /* reverse the given text */
      reversed = translate_session_translate_text(session, argv[1], "en", "en-x-rev",
    					      NULL, NULL, &err);

      /* handle failure */
      if (! reversed)
        {
          g_printerr("Unable to reverse text: %s\n", err->message);
          g_error_free(err);
          exit(1);
        }

      /* success, print the reversed text, cleanup and exit */
      g_print("%s", reversed);
      g_free(reversed);
      g_object_unref(session);

      return 0;
    }

    #else /* ! STANDALONE */

    G_MODULE_EXPORT gboolean
    translate_module_init (GError **err)
    {
      TranslateService *service;

      /* register our custom tag */
      reverse_service_register_tag();

      /* add the reverse service */
      service = reverse_service_new();
      translate_add_service(service);
      g_object_unref(service);

      return TRUE;			/* success */
    }

    #endif /* ! STANDALONE */