GNU gettext

https://www.gnu.org/software/gettext/
Admin
GNU gettext is a framework and set of tools that provides a well-integrated solution for adding...
Tokens:449,795
Snippets:2,942
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install gettext-stub via opam

Source: https://www.gnu.org/software/gettext/manual/html_node/OCaml.html

Install the OCaml gettext stub library using opam.

```shell
opam install gettext-stub
```

--------------------------------

### Example PO file1.po entry

Source: https://www.gnu.org/software/gettext/manual/gettext.txt

Example entry from file1.po used to illustrate how msgcat accumulates divergent translations.

```po
#: src/hello.c:200
#, c-format
msgid "Report bugs to <%s>.\n"
msgstr "Comunicar `bugs' a <%s>.\n"
```

--------------------------------

### Example POTFILES.in file

Source: https://www.gnu.org/software/gettext/manual/html_node/po_002fPOTFILES_002ein.html

Example of a POTFILES.in file listing source files with translatable strings. Hash-marked comments and blank lines are ignored. Paths are relative to the top level of the distribution, not the po/ directory.

```plaintext
# List of source files containing translatable strings.
# Copyright (C) 1995 Free Software Foundation, Inc.

# Common library files
lib/error.c
lib/getopt.c
lib/xmalloc.c

# Package source files
src/gettext.c
src/msgfmt.c
src/xgettext.c

```

--------------------------------

### Example PO file2.po entry

Source: https://www.gnu.org/software/gettext/manual/gettext.txt

Example entry from file2.po used to illustrate how msgcat accumulates divergent translations.

```po
#: src/bye.c:100
#, c-format
msgid "Report bugs to <%s>.\n"
msgstr "Comunicar \"bugs\" a <%s>.\n"
```

--------------------------------

### Check gettext locale with gettext --version and --help

Source: https://www.gnu.org/software/gettext/FAQ.html

Check that the environment variables (LC_ALL, LC_MESSAGES, LC_CTYPE, LANG, LANGUAGE) specify a valid locale and language. If you see at least some output in your desired language, the locale setup is correct; otherwise, either the chosen language is too exotic (gettext is localized to 33 languages) or the environment variables are inconsistent (e.g., LC_ALL points to a not installed locale or LC_MESSAGES and LC_CTYPE are inconsistent).

```bash
$ gettext --version
$ gettext --help
```

--------------------------------

### libgettextpo Usage Example

Source: https://www.gnu.org/software/gettext/manual/html_node/libgettextpo.html

Example code demonstrating how to use the libgettextpo library to read a PO file, iterate over its messages, modify them, and write the result back.

```APIDOC
## libgettextpo Usage Example

### Description
This example shows how to use the libgettextpo C library to read a PO file, iterate over its messages, modify them, and write the result back. Error handling is delegated to user-provided functions.

### Functions Used
- `po_file_read`
- `po_file_domains`
- `po_message_iterator`
- `po_next_message`
- `po_message_msgid`
- `po_message_msgstr`
- `po_message_set_fuzzy`
- `po_message_iterator_free`
- `po_file_write`
- `po_file_free`

### Code Example
```c
struct po_xerror_handler handler =
  {
    .xerror = ...,
    .xerror2 = ...
  };
const char *filename = ...;
/* Read the file into memory.  */
po_file_t file = po_file_read (filename, &handler);

{
  const char * const *domains = po_file_domains (file);
  const char * const *domainp;

  /* Iterate the domains contained in the file.  */
  for (domainp = domains; *domainp; domainp++)
    {
      po_message_t *message;
      const char *domain = *domainp;
      po_message_iterator_t iterator = po_message_iterator (file, domain);

      /* Iterate each message inside the domain.  */
      while ((message = po_next_message (iterator)) != NULL)
        {
          /* Read data from the message ...  */
          const char *msgid = po_message_msgid (message);
          const char *msgstr = po_message_msgstr (message);

          ...

          /* Modify its contents ...  */
          if (perform_some_tests (msgid, msgstr))
            po_message_set_fuzzy (message, 1);

          ...
        }
      /* Always release returned po_message_iterator_t.  */
      po_message_iterator_free (iterator);
    }

  /* Write back the result.  */
  po_file_t result = po_file_write (file, filename, &handler);
}

/* Always release the returned po_file_t.  */
po_file_free (file);
```

### Notes
- The library is multithread-safe: different threads can safely use the functions on unrelated data objects.
- Always release returned `po_message_iterator_t` and `po_file_t` objects.
```

--------------------------------

### Example 'dist:' goal in Makefile.in

Source: https://www.gnu.org/software/gettext/manual/html_node/Makefile.html

Example of a 'dist:' goal that creates a distribution directory, copies files, recurses into subdirectories, and creates a tarball. The po/Makefile assumes the proper directory has been set up from the main Makefile.

```makefile
distdir = $(PACKAGE)-$(VERSION)
dist: Makefile
	rm -fr $(distdir)
	mkdir $(distdir)
	chmod 777 $(distdir)
	for file in $(DISTFILES); do \
	  ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
	done
	for subdir in $(SUBDIRS); do \
	  mkdir $(distdir)/$$subdir || exit 1; \
	  chmod 777 $(distdir)/$$subdir; \
	  (cd $$subdir && $(MAKE) $@) || exit 1; \
	done
	tar chozf $(distdir).tar.gz $(distdir)
	rm -fr $(distdir)

```

--------------------------------

### Locating rules file example (messages.loc)

Source: https://www.gnu.org/software/gettext/manual/html_node/Locating-Rules.html

Example of a locating rules file that associates the ITS rules file 'messages.its' with XML files matching '*.xml' (with root element 'messages') and with files matching '*.msg'. The file must have a .loc extension and be installed in $prefix/share/gettext/its.

```xml
<?xml version="1.0"?>
<locatingRules>
  <locatingRule name="Messages" pattern="*.xml">
    <documentRule localName="messages" target="messages.its"/>
  </locatingRule>
  <locatingRule name="Messages" pattern="*.msg" target="messages.its"/>
</locatingRules>

```

--------------------------------

### Initialize a PO file with msginit

Source: https://www.gnu.org/software/gettext/manual/html_node/Creating.html

Use this command sequence to create or update a PO file for a new or existing translation. Run it from the package directory, then the po subdirectory, and it will guide you through the process.

```shell
$ cd PACKAGE-VERSION
$ cd po
$ msginit

```

--------------------------------

### Here documents with gettext

Source: https://www.gnu.org/software/gettext/manual/html_node/Quote_002dlike-Expressions.html

Examples of here documents passed to gettext. Here-documents are recognized; if the delimiter is enclosed in single quotes, the string is not interpolated; if it is enclosed in double quotes or has no quotes, the string is interpolated. Delimiters that start with a digit are not supported.

```perl
print gettext <<'EOF';
program not found in $PATH
EOF

print ngettext <<EOF, <<"EOF";
one file deleted
EOF
several files deleted
EOF
```

--------------------------------

### Create a new PO file with msginit

Source: https://www.gnu.org/software/gettext/manual/gettext.txt

Navigates to the package and po directories, then runs msginit to create a new PO file.

```shell
$ cd PACKAGE-VERSION
$ cd po
$ msginit
```

--------------------------------

### Set LANG environment variable in csh, sh, and bash

Source: https://www.gnu.org/software/gettext/manual/gettext.txt

Set the LANG environment variable to the appropriate LL_CC combination to use installed translations. Unset LC_ALL or other LC_xxx variables first, otherwise LANG will not have the desired effect. The examples show the syntax for csh, sh, and bash shells.

```csh
setenv LANG de_DE
```

```sh
export LANG; LANG=de_DE
```

```bash
export LANG=de_DE
```

--------------------------------

### printf approach example with shell variable pid

Source: https://www.gnu.org/software/gettext/manual/html_node/The-printf-approach.html

Uses env printf with a gettext substitution to print a localized message containing the shell variable pid. Requires a POSIX:2024 compliant printf, such as GNU coreutils 9.6+, FreeBSD 11+, or Solaris 11 OpenIndiana/OmniOS. The strings passed to gettext must not start or end with a newline.

```shell
env printf "`gettext \"Running as process number %u.\"`"'\n' $pid

```

--------------------------------

### Library initialization with bindtextdomain

Source: https://www.gnu.org/software/gettext/manual/gettext.txt

Minimal initialization for a library, reduced to a single bindtextdomain call.

```C
bindtextdomain (PACKAGE, LOCALEDIR);
```

--------------------------------

### xgettext sample invocation with keyword and flag options

Source: https://www.gnu.org/software/gettext/manual/html_node/xgettext-Invocation.html

Example command for extracting translatable strings from src/hello.c, using '_' as the gettext shorthand. It sets the output file to hello.pot, adds comments with the TRANSLATORS: prefix, defines the keyword '_' and the flag for C format, and specifies the source directory.

```shell
xgettext -o hello.pot \
         --add-comments=TRANSLATORS: \
         --keyword=_ --flag=_:1:pass-c-format \
         --directory=.. \
         src/hello.c

```

--------------------------------

### Example dist goal in main Makefile.in

Source: https://www.gnu.org/software/gettext/manual/gettext.txt

A dist goal that creates a distribution directory, copies files, recurses into subdirectories, and creates a tarball.

```makefile
distdir = $(PACKAGE)-$(VERSION)
dist: Makefile
	rm -fr $(distdir)
	mkdir $(distdir)
	chmod 777 $(distdir)
	for file in $(DISTFILES); do \
	  ln $$file $(distdir) 2>/dev/null || cp -p $$file $(distdir); \
	done
	for subdir in $(SUBDIRS); do \
	  mkdir $(distdir)/$$subdir || exit 1; \
	  chmod 777 $(distdir)/$$subdir; \
	  (cd $$subdir && $(MAKE) $@) || exit 1; \
	done
	tar chozf $(distdir).tar.gz $(distdir)
	rm -fr $(distdir)
```

--------------------------------

### Program initialization with setlocale, bindtextdomain, and textdomain

Source: https://www.gnu.org/software/gettext/manual/gettext.txt

Initialization sequence for a program using gettext. Must be called before any translatable strings are used.

```C
setlocale (LC_ALL, "");
bindtextdomain (PACKAGE, LOCALEDIR);
textdomain (PACKAGE);
```

--------------------------------

### Define PACKAGE and VERSION in Makefile.in

Source: https://www.gnu.org/software/gettext/manual/html_node/Makefile.html

Add these lines near the beginning of the top-level Makefile.in so that the 'dist:' goal works properly.

```makefile
PACKAGE = @PACKAGE@
VERSION = @VERSION@

```

--------------------------------

### Example translatable string in decent English style

Source: https://www.gnu.org/software/gettext/manual/gettext.txt

Example of a translatable string that follows the guideline of using decent English style.

```C
"%s: is parameter\n"
```

--------------------------------

### GPL source file header notice

Source: https://www.gnu.org/software/gettext/libasprintf/manual/html_node/GNU-GPL.html

Attach this notice to the start of each source file to convey the exclusion of warranty and provide a pointer to the full license. Replace 'one line to give the program's name and a brief idea of what it does.' and 'Copyright (C) yyyy  name of author' with actual program details.

```text
one line to give the program's name and a brief idea of what it does.
Copyright (C) yyyy  name of author

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, see <https://www.gnu.org/licenses/>.

```

--------------------------------

### Polish plural forms example

Source: https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html

An example of plural forms in Polish, showing that the number of plural forms and their construction differ across languages.

```text
1 plik
2,3,4 pliki
5-21 pliko'w
22-24 pliki
25-31 pliko'w

```

--------------------------------

### Hierarchical CSS Selector Example

Source: https://www.gnu.org/software/gettext/libtextstyle/manual/libtextstyle.txt

An example of combining CSS classes to create a hierarchical selector for highlighting non-ASCII words within strings.

```css
.string .non-ascii { color: red; }
```
Tokens:
Raw