(gettext.info)libgettextpo

---

Prev: Colorizing Up: Manipulating

---

Enter node , (file) or (file)node

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