(gettext.info.gz) libgettextpo

Info Catalog

(gettext.info.gz) msgexec Invocation

(gettext.info.gz) Manipulating

 
 9.11 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);
 

Info Catalog

(gettext.info.gz) msgexec Invocation

(gettext.info.gz) Manipulating