9.12 Writing your own programs that process PO files

For the tasks for which a combination of ‘msgattrib’, ‘msgcat’ etc. is not sufficient, a set of C functions is provided in a library, to make it possible to process PO files in your own programs. When you use this library, you don’t need to write routines to parse the PO file; instead, you retrieve a pointer in memory to each of messages contained in the PO file. Functions for writing PO files are not provided at this time.

The functions are declared in the header file ‘<gettext-po.h>’, and are defined in a library called ‘libgettextpo’.

Data Type: po_file_t

This is a pointer type that refers to the contents of a PO file, after it has been read into memory.

Data Type: po_message_iterator_t

This is a pointer type that refers to an iterator that produces a sequence of messages.

Data Type: po_message_t

This is a pointer type that refers to a message of a PO file, including its translation.

Function: po_file_t po_file_read (const char *filename)

The po_file_read function reads a PO file into memory. The file name is given as argument. The return value is a handle to the PO file’s contents, valid until po_file_free is called on it. In case of error, the return value is NULL, and errno is set.

Function: void po_file_free (po_file_t file)

The po_file_free function frees a PO file’s contents from memory, including all messages that are only implicitly accessible through iterators.

Function: const char * const * po_file_domains (po_file_t file)

The po_file_domains function returns the domains for which the given PO file has messages. The return value is a NULL terminated array which is valid as long as the file handle is valid. For PO files which contain no ‘domain’ directive, the return value contains only one domain, namely the default domain "messages".

Function: po_message_iterator_t po_message_iterator (po_file_t file, const char *domain)

The po_message_iterator returns an iterator that will produce the messages of file that belong to the given domain. If domain is NULL, the default domain is used instead. To list the messages, use the function po_next_message repeatedly.

Function: void po_message_iterator_free (po_message_iterator_t iterator)

The po_message_iterator_free function frees an iterator previously allocated through the po_message_iterator function.

Function: po_message_t po_next_message (po_message_iterator_t iterator)

The po_next_message function returns the next message from iterator and advances the iterator. It returns NULL when the iterator has reached the end of its message list.

The following functions returns details of a po_message_t. Recall that the results are valid as long as the file handle is valid.

Function: const char * po_message_msgid (po_message_t message)

The po_message_msgid function returns the msgid (untranslated English string) of a message. This is guaranteed to be non-NULL.

Function: const char * po_message_msgid_plural (po_message_t message)

The po_message_msgid_plural function returns the msgid_plural (untranslated English plural string) of a message with plurals, or NULL for a message without plural.

Function: const char * po_message_msgstr (po_message_t message)

The po_message_msgstr function returns the msgstr (translation) of a message. For an untranslated message, the return value is an empty string.

Function: const char * po_message_msgstr_plural (po_message_t message, int index)

The po_message_msgstr_plural function returns the msgstr[index] of a message with plurals, or NULL when the index is out of range or for a message without plural.

Here is an example code how these functions can be used.

const char *filename = …;
po_file_t file = po_file_read (filename);

if (file == NULL)
  error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
{
  const char * const *domains = po_file_domains (file);
  const char * const *domainp;

  for (domainp = domains; *domainp; domainp++)
    {
      const char *domain = *domainp;
      po_message_iterator_t iterator = po_message_iterator (file, domain);

      for (;;)
        {
          po_message_t *message = po_next_message (iterator);

          if (message == NULL)
            break;
          {
            const char *msgid = po_message_msgid (message);
            const char *msgstr = po_message_msgstr (message);

            …
          }
        }
      po_message_iterator_free (iterator);
    }
}
po_file_free (file);