Usage Guide

C++ Header-Only Library

Add the include/ directory to your include path and use:

#include <gettext/gettext.hpp>

All functions are in the intl namespace. No linking is required.

Domain Management

// Set the directory where locale catalogs are stored
intl::bindtextdomain("myapp", "/usr/share/locale");

// Set the current text domain
intl::textdomain("myapp");

// Optionally set output charset
intl::bind_textdomain_codeset("myapp", "UTF-8");

Translation Lookup

// Simple translation
const char* msg = intl::gettext("Hello");

// Translation in a specific domain
const char* msg2 = intl::dgettext("other_domain", "Hello");

// Translation with explicit LC category
const char* msg3 = intl::dcgettext("myapp", "Hello", LC_MESSAGES);

Plural Forms

int n = get_file_count();
const char* msg = intl::ngettext("file", "files", n);
printf("%d %s\n", n, msg);

The correct plural form is selected automatically based on the Plural-Forms header in the loaded .mo catalog.

Context-Qualified Translations

When the same English string has different translations depending on context:

// "Open" as a menu action
const char* menu_open = intl::pgettext("menu", "Open");

// "Open" as a status indicator
const char* status_open = intl::pgettext("status", "Open");

C API

Link with -lintl and include <libintl.h>:

#include <libintl.h>

textdomain("myapp");
bindtextdomain("myapp", "/usr/share/locale");
printf("%s\n", gettext("Hello"));
printf("%s\n", ngettext("file", "files", count));

Context lookups use macros in C:

printf("%s\n", pgettext("menu", "Open"));

Locale Resolution

The library checks environment variables in this order:

LANGUAGE — colon-separated list (e.g., fr:de:en)
LC_ALL
LC_MESSAGES (or the specific LC_* category)
LANG

If the resolved locale is C or POSIX, no translations are loaded.

The catalog file path is constructed as:

<base_dir>/<locale>/LC_MESSAGES/<domain>.mo

Where <base_dir> defaults to /usr/local/share/locale unless overridden by bindtextdomain().