FreeBSD Porter's Handbook
Prev | Chapter 6 Special considerations | Next

# 6.5 Using GNU `gettext`

## 6.5.1 Basic usage

If your port requires `gettext`, just set `USE_GETTEXT` to `yes`, and your port will grow the dependency on `devel/gettext`. The value of `USE_GETTEXT` can also specify the required version of the `libintl` library, the basic part of `gettext`, but using this feature is strongly discouraged: Your port should work with just the current version of `devel/gettext`.

A rather common case is a port using `gettext` and `configure`. Generally, GNU `configure` should be able to locate `gettext` automatically. If it ever fails to, hints at the location of `gettext` can be passed in `CPPFLAGS` and `LDFLAGS` as follows:

    USE_GETTEXT=    yes
    CPPFLAGS+=      -I${LOCALBASE}/include
    LDFLAGS+=       -L${LOCALBASE}/lib

    GNU_CONFIGURE=  yes
    CONFIGURE_ENV=  CPPFLAGS="${CPPFLAGS}" \
                    LDFLAGS="${LDFLAGS}"

Of course, the code can be more compact if there are no more flags to pass to `configure`:

    USE_GETTEXT=    yes
    GNU_CONFIGURE=  yes
    CONFIGURE_ENV=  CPPFLAGS="-I${LOCALBASE}/include" \
                    LDFLAGS="-L${LOCALBASE}/lib"

## 6.5.2 Optional usage

Some software products allow for disabling NLS, e.g., through passing `--disable-nls` to `configure`. In that case, your port should use `gettext` conditionally, depending on the status of `WITHOUT_NLS`. For ports of low to medium complexity, you can rely on the following idiom:

    GNU_CONFIGURE=          yes

    .if !defined(WITHOUT_NLS)
    USE_GETTEXT=            yes
    PLIST_SUB+=             NLS=""
    .else
    CONFIGURE_ARGS+=        --disable-nls
    PLIST_SUB+=             NLS="@comment "
    .endif

The next item on your to-do list is to arrange so that the message catalog files are included in the packing list conditionally. The `Makefile` part of this task is already provided by the idiom. It is explained in the section on advanced `pkg-plist` practices. In a nutshell, each occurrence of `%%NLS%%` in `pkg-plist` will be replaced by ```@comment` '' if NLS is disabled, or by a null string if NLS is enabled. Consequently, the lines prefixed by `%%NLS%%` will become mere comments in the final packing list if NLS is off; otherwise the prefix will be just left out. All you need to do now is insert `%%NLS%%` before each path to a message catalog file in `pkg-plist`. For example:

    %%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
    %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo

In high complexity cases, you may need to use more advanced techniques than the recipe given here, such as dynamic packing list generation.

## 6.5.3 Handling message catalog directories

There is a point to note about installing message catalog files. The target directories for them, which reside under ``LOCALBASE`/share/locale`, should rarely be created and removed by your port. The most popular languages have their respective directories listed in `/etc/mtree/BSD.local.dist`; that is, they are a part of the base system. The directories for many other languages are governed by the `devel/gettext` port. You may want to consult its `pkg-plist` and see whether your port is going to install a message catalog file for a unique language.

Prev | Home | Next
Using GNU autotools | Up | Using `perl`

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.