The gettext Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The gettext Reference Manual

This is the gettext Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:41:22 2022 GMT+0.

Table of Contents


1 Introduction

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?


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 gettext

An pure Common Lisp implementation of gettext runtime. gettext is an internationalization and localization (i18n) system commonly used for writing multilingual programs on Unix-like computer operating systems.

Author

Thomas Bakketun <thomas.bakketun@copyleft.no>

License

GNU Lesser General Public Licence 3.0

Dependencies
  • split-sequence (system).
  • yacc (system).
  • flexi-streams (system).
Source

gettext.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 gettext/gettext.asd

Source

gettext.asd.

Parent Component

gettext (system).

ASDF Systems

gettext.


3.1.2 gettext/packages.lisp

Source

gettext.asd.

Parent Component

gettext (system).

Packages

gettext.


3.1.3 gettext/plurals-0.lisp

Dependency

packages.lisp (file).

Source

gettext.asd.

Parent Component

gettext (system).

Internals

op2 (function).


3.1.4 gettext/plurals.lisp

Dependency

plurals-0.lisp (file).

Source

gettext.asd.

Parent Component

gettext (system).

Internals

Previous: , Up: Lisp   [Contents][Index]

3.1.5 gettext/gettext.lisp

Dependency

plurals.lisp (file).

Source

gettext.asd.

Parent Component

gettext (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 gettext

Source

packages.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.1 Special variables

Special Variable: *current-locale*
Package

gettext.

Source

gettext.lisp.


5.1.2 Macros

Macro: preload-catalogs (textdomaindir)
Package

gettext.

Source

gettext.lisp.

Macro: setup-gettext (package default-domain)
Package

gettext.

Source

gettext.lisp.


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.3 Ordinary functions

Function: catalog-meta* (&optional domain catergory locale)
Package

gettext.

Source

gettext.lisp.

Function: gettext* (msgid &optional domain category locale)
Package

gettext.

Source

gettext.lisp.

Function: gettext-noop (msgid)
Package

gettext.

Source

gettext.lisp.

Function: ngettext* (msgid1 msgid2 n &optional domain category locale)
Package

gettext.

Source

gettext.lisp.

Function: textdomain ()
Package

gettext.

Source

gettext.lisp.

Function: (setf textdomain) ()
Package

gettext.

Source

gettext.lisp.

Function: textdomaindir (domain)
Package

gettext.

Source

gettext.lisp.

Function: (setf textdomaindir) (domain)
Package

gettext.

Source

gettext.lisp.


5.1.4 Types

Type: lc-category ()
Package

gettext.

Source

gettext.lisp.


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *catalog-cache*
Package

gettext.

Source

gettext.lisp.

Special Variable: *plural-expression-parser*
Package

gettext.

Source

plurals.lisp.

Special Variable: *textdomain*
Package

gettext.

Source

gettext.lisp.

Special Variable: *textdomaindirs*
Package

gettext.

Source

gettext.lisp.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary functions

Reader: catalog-headers (instance)
Writer: (setf catalog-headers) (instance)
Package

gettext.

Source

gettext.lisp.

Target Slot

headers.

Reader: catalog-key (instance)
Writer: (setf catalog-key) (instance)
Package

gettext.

Source

gettext.lisp.

Target Slot

key.

Reader: catalog-messages (instance)
Writer: (setf catalog-messages) (instance)
Package

gettext.

Source

gettext.lisp.

Target Slot

messages.

Reader: catalog-nplurals (instance)
Writer: (setf catalog-nplurals) (instance)
Package

gettext.

Source

gettext.lisp.

Target Slot

nplurals.

Function: catalog-p (object)
Package

gettext.

Source

gettext.lisp.

Function: catalog-pathname (key)
Package

gettext.

Source

gettext.lisp.

Reader: catalog-plurals-function (instance)
Writer: (setf catalog-plurals-function) (instance)
Package

gettext.

Source

gettext.lisp.

Target Slot

plurals-function.

Function: compile-plural (expr)
Package

gettext.

Source

plurals.lisp.

Function: construct-catalog (key messages)
Package

gettext.

Source

gettext.lisp.

Function: copy-catalog (instance)
Package

gettext.

Source

gettext.lisp.

Function: decode-catalog-pathname (pathname)
Package

gettext.

Source

gettext.lisp.

Function: define-catalog (key &optional messages)
Package

gettext.

Source

gettext.lisp.

Function: digitp (c)
Package

gettext.

Source

plurals.lisp.

Function: get-catalog (locale category domain)
Package

gettext.

Source

gettext.lisp.

Function: lexer (stream)
Package

gettext.

Source

plurals.lisp.

Function: lookup (msgid domain category locale)
Package

gettext.

Source

gettext.lisp.

Function: make-catalog (&key key headers nplurals plurals-function messages)
Package

gettext.

Source

gettext.lisp.

Function: null-split (string)
Package

gettext.

Source

gettext.lisp.

Function: op2 (a b c)
Package

gettext.

Source

plurals-0.lisp.

Function: parse-headers (string)
Package

gettext.

Source

gettext.lisp.

Function: parse-plural (string)
Package

gettext.

Source

plurals.lisp.

Function: parse-plurals-form (string)
Package

gettext.

Source

plurals.lisp.

Function: read-mo (pathname)
Package

gettext.

Source

gettext.lisp.

Function: transform (expr)
Package

gettext.

Source

plurals.lisp.


5.2.3 Structures

Structure: catalog
Package

gettext.

Source

gettext.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: key
Readers

catalog-key.

Writers

(setf catalog-key).

Slot: headers
Readers

catalog-headers.

Writers

(setf catalog-headers).

Slot: nplurals
Readers

catalog-nplurals.

Writers

(setf catalog-nplurals).

Slot: plurals-function
Readers

catalog-plurals-function.

Writers

(setf catalog-plurals-function).

Slot: messages
Readers

catalog-messages.

Writers

(setf catalog-messages).


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
C   D   F   G   L   M   N   O   P   R   S   T  
Index Entry  Section

(
(setf catalog-headers): Private ordinary functions
(setf catalog-key): Private ordinary functions
(setf catalog-messages): Private ordinary functions
(setf catalog-nplurals): Private ordinary functions
(setf catalog-plurals-function): Private ordinary functions
(setf textdomain): Public ordinary functions
(setf textdomaindir): Public ordinary functions

C
catalog-headers: Private ordinary functions
catalog-key: Private ordinary functions
catalog-messages: Private ordinary functions
catalog-meta*: Public ordinary functions
catalog-nplurals: Private ordinary functions
catalog-p: Private ordinary functions
catalog-pathname: Private ordinary functions
catalog-plurals-function: Private ordinary functions
compile-plural: Private ordinary functions
construct-catalog: Private ordinary functions
copy-catalog: Private ordinary functions

D
decode-catalog-pathname: Private ordinary functions
define-catalog: Private ordinary functions
digitp: Private ordinary functions

F
Function, (setf catalog-headers): Private ordinary functions
Function, (setf catalog-key): Private ordinary functions
Function, (setf catalog-messages): Private ordinary functions
Function, (setf catalog-nplurals): Private ordinary functions
Function, (setf catalog-plurals-function): Private ordinary functions
Function, (setf textdomain): Public ordinary functions
Function, (setf textdomaindir): Public ordinary functions
Function, catalog-headers: Private ordinary functions
Function, catalog-key: Private ordinary functions
Function, catalog-messages: Private ordinary functions
Function, catalog-meta*: Public ordinary functions
Function, catalog-nplurals: Private ordinary functions
Function, catalog-p: Private ordinary functions
Function, catalog-pathname: Private ordinary functions
Function, catalog-plurals-function: Private ordinary functions
Function, compile-plural: Private ordinary functions
Function, construct-catalog: Private ordinary functions
Function, copy-catalog: Private ordinary functions
Function, decode-catalog-pathname: Private ordinary functions
Function, define-catalog: Private ordinary functions
Function, digitp: Private ordinary functions
Function, get-catalog: Private ordinary functions
Function, gettext*: Public ordinary functions
Function, gettext-noop: Public ordinary functions
Function, lexer: Private ordinary functions
Function, lookup: Private ordinary functions
Function, make-catalog: Private ordinary functions
Function, ngettext*: Public ordinary functions
Function, null-split: Private ordinary functions
Function, op2: Private ordinary functions
Function, parse-headers: Private ordinary functions
Function, parse-plural: Private ordinary functions
Function, parse-plurals-form: Private ordinary functions
Function, read-mo: Private ordinary functions
Function, textdomain: Public ordinary functions
Function, textdomaindir: Public ordinary functions
Function, transform: Private ordinary functions

G
get-catalog: Private ordinary functions
gettext*: Public ordinary functions
gettext-noop: Public ordinary functions

L
lexer: Private ordinary functions
lookup: Private ordinary functions

M
Macro, preload-catalogs: Public macros
Macro, setup-gettext: Public macros
make-catalog: Private ordinary functions

N
ngettext*: Public ordinary functions
null-split: Private ordinary functions

O
op2: Private ordinary functions

P
parse-headers: Private ordinary functions
parse-plural: Private ordinary functions
parse-plurals-form: Private ordinary functions
preload-catalogs: Public macros

R
read-mo: Private ordinary functions

S
setup-gettext: Public macros

T
textdomain: Public ordinary functions
textdomaindir: Public ordinary functions
transform: Private ordinary functions

Jump to:   (  
C   D   F   G   L   M   N   O   P   R   S   T