gettext for Common Lisp
=======================

This is a port of the GNU gettext runtime to Common Lisp. For more
information about GNU gettext see http://www.gnu.org/software/gettext/.


Highlights
----------

* Implemented in Common Lisp. No need for any C libraries.
* Use GNU gettext tools during development.
* Supports multithreaded applications with different langauge in each thread.
* Translations can be embedded into compiled applications.


Download and installation
-------------------------

The libarary has some dependencies, so the easiest way is to use
Quicklisp, see http://www.quicklisp.org/

Get the gettext sources from GitHub:

    cd quicklisp/local-projects
    git clone git://github.com/copyleft/gettext.git
    ln -s gettext/gettext-example .

Then load it:

    (ql:quickload "gettext")

Eventually gettext will become part of quicklisp, and only the last
step will be neccary (unless you need the latest version).


How to use
----------

This library reimplements only the runtime part of GNU gettext in
Common Lisp. In order to successfully use this library you need to
install the GNU gettext tools. No GNU gettext tools or library are
needed at runtime.

The easiest way to get started is to look at the sample application
located in the subdirectory gettext-example.

Step 1: Add gettext as a dependency to your system definition
(gettext-example.asd):

    :depends-on (:gettext)

Step 2: Add the GETTEXT package to the use list of you applications
package. Setup gettext in your applications package (package.lisp):

    (gettext:setup-gettext #:example "gettext-example")

The first parameter is the name of the package. The second parameter
is the textdomain. Textdomains are namespaces for the translated
text. For most application a single textdomain (with the same name as
the asdf system) will suffice.

Step 3: Load the translated messages (example.lisp):

    (preload-catalogs #.(asdf:system-relative-pathname :gettext-example "locale/"))

This macro takes a single parameter, the pathname of a directory tree
containing translation catalogs in MO format. The texts are loaded at
compile time and become part of the compiled file, thus the the MO
files are not need at runtime. An alternative approch is to load the
MO files at runtime, see the section "Loading catalogs at runtime".

Step 4: Make sure the current locale is set by binding the special
variable GETTEXT:*CURRENT-LOCALE*:

    (setf *current-locale* "nn")

Here the locale is hardcoded to "nn". In a real world application it
would be set to the current users preferred language. If the
application is a multithreaded multiuser application (like most web
applications), dynamically bind GETTEXT:*CURRENT-LOCALE* to the logged
in users preferred language.

Step 5: Mark texts for translation, e.g.:

    (write-line (_ "This is an example gettext program."))

Extract the texts for translations using the xgettext program from GNU
gettext. This step will have to be repeated whenver the texts are
updated in the source code. See update-translations.sh for a script
that automates this job.

Step 6: Translate the texts. First create a PO file for the langauge,
using the msginit tool. Then you edit this file using e.g. Emacs with
po-mode. The PO file can easly be updated with new texts with the help
of the msgmerge tool. See update-translations.sh.

Step 7: Finally convert the PO files into MO files using msgfmt. See
update-translations.sh for details.


Loading catalogs at runtime
---------------------------

Replace GETTEXT:PRELOAD-CATALOGS with a SETF of the place
GETTEXT:TEXTDOMAINDIR:

    (setf (textdomaindir "gettext-example")
          (asdf:system-relative-pathname :gettext-example "locale/"))

The catalogs will be loaded as needed and cached until the
appliciatons quits.


Reference
---------

Special variable
GETTEXT:*CURRENT-LOCALE*

This variable must be bound to a string denoting the current
locale. The library does not try to decode this string any way, it
simply uses it to look for message catalogs in the file system. It's
recommended to use the two letter language codes defined in ISO 639-1.
A list can be found here:
http://www.gnu.org/software/gettext/manual/gettext.html#Language-Codes


Macro
GETTEXT:SETUP-GETTEXT package default-domain

Defines gettext lookup functions in the provided package. _ and
GETTEXT is as shortcut for GETTEXT:GETTEXT* and NGETTEXT is a shortcut
for GETTEXT:NGETTEXT*, but with default-domain as the default
domain. N_ is simply a shortcut for GETTEXT:GETTEXT-NOOP.


Place
GETTEXT:TEXTDOMAINDIR domain
(SETF (GETTEXT:TEXTDOMAINDIR domain) directory)

Specifies where to find translation catalogs for the given domain. The
directory is the base directory used for lookup. The actual name of
message catalog will be TEXTDOMAINDIR/l/LC_MESSAGES/domain.mo, where
TEXTDOMAINDIR is the directory given setf to GETTEXT:TEXTDOMAINDIR, l
is the current locale, LC_MESSAGES is the category and domain is the
text domain.

Place
GETTEXT:TEXTDOMAIN
(SETF (GETTEXT:TEXTDOMAIN) domain)

Returns or sets the default text domain used by GETTEXT:GETTEXT* and
GETTEXT:NGETTEXT*. Shortcut lookup functions defined by
GETTEXT:SETUP-GETTEXT ignores this place.


Function
GETTEXT:GETTEXT* msgid &optional domain category locale

Lookup a translated using the provided msgid. Domain defaults to
(GETTEXT:TEXTDOMAIN). Category defaults to :LC_MESSAGES, and locale
defaults to GETTEXT:*CURRENT-LOCALE*.


Function
GETTEXT:NGETTEXT* msgid1 msgid2 n &optional domain category locale

Lookup a plural translated text. msgid1 is the singular form, msgid2
is the plural form and n is the number used to decide which plural
form to use. See GETTEXT:GETTEXT* for description of the optional
parameters.


Function
GETTEXT:GETTEXT-NOOP msgid

This function simply returns its msgid parameter untranslated. It's
only used to mark texts that shall be translated, but where the text
occurs in an expression that will be executed at compile time. Example:

    (defparameter *greeting* (gettext-noop "Hello world"))
    ;; In some function:
       (write-line (gettext* *greeting*))


Macro
GETTEXT:PRELOAD-CATALOGS textdomaindir

Loads all message catalogs (in every category, in every locale and
every domain) in the textdomaindir directory tree. This loading is
done at macro expantion time. The effects is as if the translated text
where part of the source code. Thus, the message catalogs are not needed
at runtime.


Type
GETTEXT:LC-CATEGORY

The allowed type of the locale parameter. One of the keyword symbols
L:LC_ADDRESS, :LC_ALL, :LC_COLLATE, :LC_CTYPE, :LC_IDENTIFICATION,
:LC_MEASUREMENT, :LC_MESSAGES, :LC_MONETARY, :LC_NAME, :LC_NUMERIC,
:LC_PAPER, :LC_TELEPHONE and :LC_TIME.


Function
GETTEXT:CATALOG-META* &optional domain category locale

Returns meta data about catalog as an assoc list. See
https://www.gnu.org/software/gettext/manual/gettext.html#Header-Entry


TODO
----

The pgettext function of GNU gettext is not implemented. Implementing
this should be fairly stright forward, but apparently the xgettext
tool doesn't support this function when extracting texts form Lisp
code.

Encoding in MO files is hardcoded to UTF-8. Is this really a problem?
Is there really a good reason for using anything else these days?