FindGettext

Finds the GNU gettext tools and provides commands for producing multi-lingual messages:

find_package(Gettext [<version>] ...)

GNU gettext is a system for internationalization (i18n) and localization (l10n), consisting of command-line tools and a runtime library (libintl). This module finds the gettext tools (such as msgmerge and msgfmt), while the runtime library can be found using the separate FindIntl module, which abstracts libintl handling across various implementations.

Common file types used with gettext:

POT files: Portable Object Template (.pot) files used as the source template for translations.
PO files: Portable Object (.po) files containing human-readable translations.
MO files: Machine Object (.mo) files compiled from .po files for runtime use.

Result Variables

This module defines the following variables:

Gettext_FOUND: Boolean indicating whether (the requested version of) gettext is found. For backward compatibility, the GETTEXT_FOUND variable is also set to the same value.
GETTEXT_VERSION_STRING: The version of gettext found.

Cache Variables

The following cache variables may also be set:

GETTEXT_MSGMERGE_EXECUTABLE: The full path to the msgmerge tool for merging message catalog and template.
GETTEXT_MSGFMT_EXECUTABLE: The full path to the msgfmt tool for compiling message catalog to a binary format.

Commands

This module provides the following commands to work with gettext in CMake, if gettext is found:

gettext_process_po_files

Creates a build rule that processes one or more .po translation files into binary .mo files for a specified translatable language locale:

gettext_process_po_files(
  <language>
  [ALL]
  [INSTALL_DESTINATION <destdir>]
  PO_FILES <po-files>...
)

This command defines a custom target that compiles the given <po-files> into .mo files for the specified <language>. On first invocation, it also creates a global custom target named pofiles, to which all subsequent invocations contribute. This target can be used to build all translation files collectively or referenced in other CMake commands.

This command should be invoked separately for each language locale to generate the appropriate .mo files per locale.

The arguments are:

<language>

The target translatable language locale of the PO files.

This string is typically formatted as a locale identifier (e.g., de_DE for German as used in Germany, or de_AT for German as used in Austria, etc.). The part before the underscore specifies the language, and the part after specifies the country or regional variant. In some cases, a shorter form using only the language code (e.g., de) may also be used.

ALL

This option adds the generated target to the default CMake build target so that translations are built by default.

INSTALL_DESTINATION <destdir>

Specifies the installation directory for the generated .mo files at the install phase. If specified, files are installed to: <destdir>/<language>/LC_MESSAGES/*.mo. If not specified, files are not installed.

PO_FILES <po-files>...

A list of one or more .po translation files to be compiled into .mo files at build phase for the specified <language>. Relative paths will be interpreted relative to the current source directory (CMAKE_CURRENT_SOURCE_DIR).

gettext_process_pot_file

Creates a build rule that processes a gettext Portable Object Template (.pot) file and associated .po files into compiled gettext Machine Object (.mo) files:

gettext_process_pot_file(
  <pot-file>
  [ALL]
  [INSTALL_DESTINATION <destdir>]
  LANGUAGES <languages>...
)

This command defines a custom target named potfiles that compiles the given <pot-file> and language-specific .po files into binary .mo files for each specified language. The corresponding <language>.po files must exist in the current binary directory (CMAKE_CURRENT_BINARY_DIR) before this command is invoked.

The arguments are:

<pot-file>: The path to the gettext Portable Object Template file (.pot) serving as the source for translations. If given as a relative path, it will be interpreted relative to the current source directory (CMAKE_CURRENT_SOURCE_DIR).
ALL: Adds the generated target to the default CMake build target so that the files are built by default.
INSTALL_DESTINATION <destdir>: Specifies the installation directory for the generated .mo files at the install phase. If specified, files are installed to: <destdir>/<language>/LC_MESSAGES/<pot-base-filename>.mo. If not specified, files are not installed.
LANGUAGES <languages>...: A list of one or more translatable language locales (e.g., en_US, fr, de_DE, zh_CN, etc.).

gettext_create_translations

Creates a build rule that processes a given .pot template file and associated .po translation files into compiled Machine Object (.mo) files:

gettext_create_translations(<pot-file> [ALL] <po-files>...)

This command defines a custom target named translations that compiles the specified <pot-file> and <po-files> into binary .mo files. It also automatically adds an install rule for the generated .mo files, installing them into the default share/locale/<language>/LC_MESSAGES/<pot-base-filename>.mo path during the install phase.

The arguments are:

<pot-file>: The path to the gettext Portable Object Template file (.pot) serving as the source for translations. If given as a relative path, it will be interpreted relative to the current source directory (CMAKE_CURRENT_SOURCE_DIR).
ALL: Adds the generated target to the default CMake build target so that translations are created by default during the build.
<po-files>...: A list of one or more translation source files in .po format, whose filenames must follow the format <language>.po. Relative paths will be interpreted relative to the current source directory (CMAKE_CURRENT_SOURCE_DIR).

Note

For better control over build and installation behavior, use gettext_process_po_files() instead.

Examples

Examples: Finding gettext

Finding the GNU gettext tools:

find_package(Gettext)

Or, finding gettext and specifying a minimum required version:

find_package(Gettext 0.21)

Or, finding gettext and making it required (if not found, processing stops with an error message):

find_package(Gettext REQUIRED)

Example: Working With gettext in CMake

When starting with gettext, .pot file is considered to be created manually. For example, using a xgettext tool on the provided main.cxx source code file:

main.cxx

#include <iostream>
#include <libintl.h>
#include <locale.h>

int main()
{
  // Set locale from environment
  setlocale(LC_ALL, "");

  // Bind the text domain
  const char* dir = std::getenv("TEXTDOMAINDIR");
  if (!dir) {
    dir = "/usr/local/share/locale";
  }
  bindtextdomain("MyApp", dir);
  textdomain("MyApp");

  std::cout << gettext("Hello, World") << std::endl;

  return 0;
}

The xgettext tool extracts all strings from gettext() calls in provided source code and creates translatable strings:

$ xgettext -o MyApp.pot main.cxx

Translatable files can be initialized by the project manually using msginit tool:

$ mkdir -p locale/de_DE
$ msginit -l de_DE.UTF8 -o locale/de_DE/MyApp.po -i MyApp.pot --no-translator

which creates a human-readable file that can be translated into a desired language (adjust as needed):

locale/de_DE/MyApp.po

msgid ""
msgstr ""
"Language: de\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

msgid "Hello, World"
msgstr "Hallo, Welt"

In CMake, the gettext_process_po_files() command provided by this module automatically creates the needed .mo files that application loads at runtime depending on the system environment variables such as LANG. In the following example, also the GNUInstallDirs module is used to provide the CMAKE_INSTALL_LOCALEDIR variable:

CMakeLists.txt

cmake_minimum_required(VERSION 3.24)
project(GettextExample)
include(GNUInstallDirs)

find_package(Gettext)

if(Gettext_FOUND)
  foreach(language IN ITEMS de_DE)
    gettext_process_po_files(
      ${language}
      ALL
      PO_FILES locale/${language}/MyApp.po
      INSTALL_DESTINATION ${CMAKE_INSTALL_LOCALEDIR}
    )
  endforeach()
endif()

add_executable(example main.cxx)

# Find and link Intl library to use gettext() from libintl.h
find_package(Intl)
target_link_libraries(example PRIVATE Intl::Intl)

install(TARGETS example)

$ cmake -B build
$ cmake --build build
$ DESTDIR=$(pwd)/stage cmake --install build

To utilize the translations, the de_DE locale needs to be enabled on the system (see locale -a). And then the localized output can be run:

$ LANG=de_DE.UTF-8 TEXTDOMAINDIR=./stage/usr/local/share/locale \
  ./stage/usr/local/bin/example

Example: Processing POT File

The gettext_process_pot_file() command processes .po translation files located in the current binary directory into .mo files:

CMakeLists.txt

find_package(Gettext)

if(Gettext_FOUND)
  set(languages de_DE fr zh_CN)

  foreach(language IN LISTS languages)
    configure_file(locale/${language}.po ${language}.po COPYONLY)
  endforeach()

  gettext_process_pot_file(
    MyApp.pot
    ALL
    INSTALL_DESTINATION ${CMAKE_INSTALL_LOCALEDIR}
    LANGUAGES ${languages}
  )
endif()

Example: Creating Translations

Using a simplified gettext_create_translations() command to create .mo files:

CMakeLists.txt

find_package(Gettext)

if(Gettext_FOUND)
  gettext_create_translations(
    MyApp.pot
    ALL
    locale/de_DE.po
    locale/fr.po
    locale/zh_CN.po
  )
endif()

FindGettext

Result Variables

Cache Variables

Commands

Examples

Examples: Finding gettext

Example: Working With gettext in CMake

Example: Processing POT File

Example: Creating Translations

See Also