# &lib; Reference Manual

## Overview

&lib; is a library for translating text and web pages between natural languages. Its modular infrastructure allows to implement new translation services separately from the core library.

&lib; is shipped with a generic module supporting web-based translation services such as Babel Fish, Google Language Tools and SYSTRAN. Moreover, the generic module allows to add new services simply by adding a few lines to a XML file (see the

services.xml

5 manual page).

&lib; is implemented on top of the GLib Object System.

### Conventions

- Unless noted otherwise, strings passed to library functions must be encoded in UTF-8.

- Unless noted otherwise, strings returned by &lib; are encoded in UTF-8.

- Unless noted otherwise, &lib; is thread-safe.

### Compiling &lib; Applications

#### Compiling on UNIX

To compile a &lib; application, you need to tell the compiler where to find the &lib; header files and libraries. This is done with the `pkg-config` utility.

The following interactive shell session demonstrates how `pkg-config` is used:

    $ pkg-config --cflags libtranslate
    -I/usr/local/include/libtranslate -I/usr/local/include/glib-2.0 -I/usr/local/lib/glib-2.0/include
    $ pkg-config --libs libtranslate
    -L/usr/local/lib -ltranslate -lgobject-2.0 -lglib-2.0 -liconv

The simplest way to compile a program is to use the "backticks" feature of the shell. If you enclose a command in backticks (not single quotes), then its output will be substituted into the command line before execution. So to compile a &lib; Hello World, you would type the following:

    $ cc `pkg-config --cflags --libs libtranslate` hello.c -o hello

#### Compiling on UNIX With Autoconf and Automake

To compile a &lib; application using GNU Autoconf and GNU Automake, insert the following line at the appropriate place in the `configure.ac` file:

    PKG_CHECK_MODULES(LIBTRANSLATE, libtranslate,, [AC_MSG_ERROR([unable to find libtranslate])])

and insert the following lines in the appropriate `Makefile.am` file:

    bin_PROGRAMS = hello
    hello_SOURCES = hello.c
    hello_CPPFLAGS = $(LIBTRANSLATE_CFLAGS)
    hello_LDFLAGS = $(LIBTRANSLATE_LIBS)

### Compiling &lib; Modules

#### Compiling on UNIX

To compile a &lib; module, you need to tell the compiler where to find the &lib; header files. This is done with the `pkg-config` utility.

For instance, to compile a &lib; Hello World module, you would type the following:

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

#### Compiling on UNIX With Autoconf, Automake and Libtool

To compile a &lib; module using GNU Autoconf, GNU Automake and GNU Libtool, insert the following line at the appropriate place in the `configure.ac` file:

    PKG_CHECK_MODULES(LIBTRANSLATE, libtranslate,, [AC_MSG_ERROR([unable to find libtranslate])])

and insert the following lines in the appropriate `Makefile.am` file:

    modulesdir = $(libdir)/libtranslate/modules
    modules_LTLIBRARIES = hello.la
    hello_la_SOURCES = hello.c
    hello_la_CPPFLAGS = $(LIBTRANSLATE_CFLAGS)
    hello_la_LDFLAGS = -avoid-version -module

#### Module Search Paths

&lib; loads modules from ``prefix`/libtranslate/modules` (where `prefix` is the prefix where &lib; is installed) and from ``~`/.libtranslate/modules` (where `~` is the path to your home directory). Filenames not having the system-specific shared object extension (usually .so) are ignored.

## Tutorials

### Translating Text or Web Pages

To translate text or web pages, you need to initialize &lib; with a call to translate_init(), create a new session using translate_session_new(), and call the appropriate translation function, translate_session_translate_text() or translate_session_translate_web_page().

#### A Simple Command-Line Translator

The following example demonstrates how to use &lib; for creating a simple command-line text and web page translator.

The source code of this example is available in the &lib; source distribution (`docs/reference/example-application.c`), and is reproduced below. On UNIX, compile it as follows:

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

    &example-application;

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

#### A Simple Service for Reversing Text

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

The source code of this example is available in the &lib; 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

    &example-service;

## API Reference

### Object Hierarchy

&index-Object-Tree;
&translate; &translate-common; &TranslatePair; &TranslateService; &TranslateSession; &translate-util;

## Built-in RFC 3066 Tag to Name Mappings

The following tag to name mappings are built into &lib;. Calling translate_get_language_name() for any tag of this table will return its localized language name.

&rfc3066-table;