gettext: libgettextpo
1
1 9.12 Writing your own programs that process PO files
1 ====================================================
1
1 For the tasks for which a combination of ‘msgattrib’, ‘msgcat’ etc.
1 is not sufficient, a set of C functions is provided in a library, to
1 make it possible to process PO files in your own programs. When you use
1 this library, you don’t need to write routines to parse the PO file;
1 instead, you retrieve a pointer in memory to each of messages contained
1 in the PO file. Functions for writing PO files are not provided at this
1 time.
1
1 The functions are declared in the header file ‘<gettext-po.h>’, and
1 are defined in a library called ‘libgettextpo’.
1
1 -- Data Type: po_file_t
1 This is a pointer type that refers to the contents of a PO file,
1 after it has been read into memory.
1
1 -- Data Type: po_message_iterator_t
1 This is a pointer type that refers to an iterator that produces a
1 sequence of messages.
1
1 -- Data Type: po_message_t
1 This is a pointer type that refers to a message of a PO file,
1 including its translation.
1
1 -- Function: po_file_t po_file_read (const char *FILENAME)
1 The ‘po_file_read’ function reads a PO file into memory. The file
1 name is given as argument. The return value is a handle to the PO
1 file’s contents, valid until ‘po_file_free’ is called on it. In
1 case of error, the return value is ‘NULL’, and ‘errno’ is set.
1
1 -- Function: void po_file_free (po_file_t FILE)
1 The ‘po_file_free’ function frees a PO file’s contents from memory,
1 including all messages that are only implicitly accessible through
1 iterators.
1
1 -- Function: const char * const * po_file_domains (po_file_t FILE)
1 The ‘po_file_domains’ function returns the domains for which the
1 given PO file has messages. The return value is a ‘NULL’
1 terminated array which is valid as long as the FILE handle is
1 valid. For PO files which contain no ‘domain’ directive, the
1 return value contains only one domain, namely the default domain
1 ‘"messages"’.
1
1 -- Function: po_message_iterator_t po_message_iterator (po_file_t FILE,
1 const char *DOMAIN)
1 The ‘po_message_iterator’ returns an iterator that will produce the
1 messages of FILE that belong to the given DOMAIN. If DOMAIN is
1 ‘NULL’, the default domain is used instead. To list the messages,
1 use the function ‘po_next_message’ repeatedly.
1
1 -- Function: void po_message_iterator_free (po_message_iterator_t
1 ITERATOR)
1 The ‘po_message_iterator_free’ function frees an iterator
1 previously allocated through the ‘po_message_iterator’ function.
1
1 -- Function: po_message_t po_next_message (po_message_iterator_t
1 ITERATOR)
1 The ‘po_next_message’ function returns the next message from
1 ITERATOR and advances the iterator. It returns ‘NULL’ when the
1 iterator has reached the end of its message list.
1
1 The following functions returns details of a ‘po_message_t’. Recall
1 that the results are valid as long as the FILE handle is valid.
1
1 -- Function: const char * po_message_msgid (po_message_t MESSAGE)
1 The ‘po_message_msgid’ function returns the ‘msgid’ (untranslated
1 English string) of a message. This is guaranteed to be non-‘NULL’.
1
1 -- Function: const char * po_message_msgid_plural (po_message_t
1 MESSAGE)
1 The ‘po_message_msgid_plural’ function returns the ‘msgid_plural’
1 (untranslated English plural string) of a message with plurals, or
1 ‘NULL’ for a message without plural.
1
1 -- Function: const char * po_message_msgstr (po_message_t MESSAGE)
1 The ‘po_message_msgstr’ function returns the ‘msgstr’ (translation)
1 of a message. For an untranslated message, the return value is an
1 empty string.
1
1 -- Function: const char * po_message_msgstr_plural (po_message_t
1 MESSAGE, int INDEX)
1 The ‘po_message_msgstr_plural’ function returns the ‘msgstr[INDEX]’
1 of a message with plurals, or ‘NULL’ when the INDEX is out of range
1 or for a message without plural.
1
1 Here is an example code how these functions can be used.
1
1 const char *filename = …;
1 po_file_t file = po_file_read (filename);
1
1 if (file == NULL)
1 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
1 {
1 const char * const *domains = po_file_domains (file);
1 const char * const *domainp;
1
1 for (domainp = domains; *domainp; domainp++)
1 {
1 const char *domain = *domainp;
1 po_message_iterator_t iterator = po_message_iterator (file, domain);
1
1 for (;;)
1 {
1 po_message_t *message = po_next_message (iterator);
1
1 if (message == NULL)
1 break;
1 {
1 const char *msgid = po_message_msgid (message);
1 const char *msgstr = po_message_msgstr (message);
1
1 …
1 }
1 }
1 po_message_iterator_free (iterator);
1 }
1 }
1 po_file_free (file);
1