Usage Guide
===========

C++ Header-Only Library
-----------------------

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

.. code-block:: cpp

   #include <gettext/gettext.hpp>

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

Domain Management
~~~~~~~~~~~~~~~~~

.. code-block:: cpp

   // 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
~~~~~~~~~~~~~~~~~~

.. code-block:: cpp

   // 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
~~~~~~~~~~~~

.. code-block:: cpp

   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:

.. code-block:: cpp

   // "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>``:

.. code-block:: c

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

.. code-block:: c

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


Locale Resolution
-----------------

The library checks environment variables in this order:

1. ``LANGUAGE`` — colon-separated list (e.g., ``fr:de:en``)
2. ``LC_ALL``
3. ``LC_MESSAGES`` (or the specific ``LC_*`` category)
4. ``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()``.