Internationalization

Translates strings with a gettext message catalog. More...

Data Structures
struct	pbl_i18n_catalog_info
	Metadata of a catalog. More...
struct	pbl_i18n_catalog
	Catalog of translations, a gettext MO file. More...

Macros
#define	PBL_I18N_LOCALE_LEN   6
	Size of an ISO locale string such as "en_US", including the terminator.
#define	PBL_I18N_NAME_LEN   30
	Size of a language name buffer, including the terminator.
#define	pbl_i18n_noop(string)   (string)
	Tag a string for extraction without translating it.
#define	pbl_i18n_ctx_noop(ctx, string)   (ctx "\4" string)
	Tag a string with a context for extraction without translating it.
#define	pbl_i18n_ctx_get(ctx, string, owner)   pbl_i18n_get(pbl_i18n_ctx_noop(ctx, string), owner)
	pbl_i18n_get() with a context.
#define	pbl_i18n_ctx_get_with_buffer(ctx, string, buffer, length)    pbl_i18n_get_with_buffer(pbl_i18n_ctx_noop(ctx, string), buffer, length)
	pbl_i18n_get_with_buffer() with a context.
#define	pbl_i18n_ctx_get_length(ctx, string)   pbl_i18n_get_length(pbl_i18n_ctx_noop(ctx, string))
	pbl_i18n_get_length() with a context.
#define	pbl_i18n_ctx_free(ctx, string, owner)   pbl_i18n_free(pbl_i18n_ctx_noop(ctx, string), owner)
	pbl_i18n_free() with a context.

Functions
int	pbl_i18n_set_catalog (const struct pbl_i18n_catalog *catalog)
	Set the catalog translations come from.
int	pbl_i18n_catalog_get_info (const struct pbl_i18n_catalog *catalog, struct pbl_i18n_catalog_info *info)
	Read the metadata of a catalog without setting it.
const char *	pbl_i18n_get (const char *string, const void *owner)
	Translate a string, caching the result for an owner.
void	pbl_i18n_get_with_buffer (const char *string, char *buffer, size_t length)
	Translate a string into a buffer.
size_t	pbl_i18n_get_length (const char *string)
	Get the length of a translated string.
void	pbl_i18n_free (const char *string, const void *owner)
	Free a cached translation.
void	pbl_i18n_free_all (const void *owner)
	Free all cached translations of an owner.
char *	pbl_i18n_get_locale (void)
	Get the ISO locale of the catalog.
uint16_t	pbl_i18n_get_version (void)
	Get the version of the catalog.
char *	pbl_i18n_get_lang_name (void)
	Get the language name of the catalog.

Detailed Description

Translates strings with a gettext message catalog.

Translations come from a catalog, a gettext MO file read through a caller-provided reader, set with pbl_i18n_set_catalog(). Strings are looked up by their English original (the msgid); when no translation exists, or no catalog is set, the original is returned. A context can be attached to disambiguate identical originals with the _ctx_ variants. Mark strings with pbl_i18n_noop() or pbl_i18n_ctx_noop() where they cannot be translated in place, so they are still extracted for translation.

Translations returned by pbl_i18n_get() are cached per owner and stay valid until freed:

text_layer_set_text(&data->title, pbl_i18n_get("Settings", data));
...
pbl_i18n_free_all(data);

For short-lived use, translate into a buffer instead:

char buf[32];
pbl_i18n_ctx_get_with_buffer("Alarm", "Snooze", buf, sizeof(buf));

The functions may be called from any thread, but not from ISRs. A catalog reader is called with the i18n lock held, so it must not call back into i18n.

---

Data Structure Documentation

pbl_i18n_catalog_info

struct pbl_i18n_catalog_info

Metadata of a catalog.

Data Fields
char	locale[PBL_I18N_LOCALE_LEN]	ISO locale such as "fr_FR".
char	name[PBL_I18N_NAME_LEN]	Language name, the locale if the catalog has none.
uint16_t	version	Catalog version.

Macro Definition Documentation

pbl_i18n_ctx_free

#define pbl_i18n_ctx_free	(		ctx,
			string,
			owner
	)		pbl_i18n_free(pbl_i18n_ctx_noop(ctx, string), owner)

pbl_i18n_free() with a context.

Parameters

ctx	Context string literal.
string	Original string literal.
owner	Owner passed to pbl_i18n_ctx_get().

pbl_i18n_ctx_get

#define pbl_i18n_ctx_get	(		ctx,
			string,
			owner
	)		pbl_i18n_get(pbl_i18n_ctx_noop(ctx, string), owner)

pbl_i18n_get() with a context.

Parameters

ctx	Context string literal.
string	Original string literal.
owner	Owner of the cached translation.

pbl_i18n_ctx_get_length

#define pbl_i18n_ctx_get_length	(		ctx,
			string
	)		pbl_i18n_get_length(pbl_i18n_ctx_noop(ctx, string))

pbl_i18n_get_length() with a context.

Parameters

ctx	Context string literal.
string	Original string literal.

pbl_i18n_ctx_get_with_buffer

#define pbl_i18n_ctx_get_with_buffer	(		ctx,
			string,
			buffer,
			length
	)		pbl_i18n_get_with_buffer(pbl_i18n_ctx_noop(ctx, string), buffer, length)

pbl_i18n_get_with_buffer() with a context.

Parameters

ctx	Context string literal.
string	Original string literal.
buffer	Output buffer.
length	Size of buffer in bytes.

pbl_i18n_ctx_noop

#define pbl_i18n_ctx_noop	(		ctx,
			string
	)		(ctx "\4" string)

Tag a string with a context for extraction without translating it.

For places where pbl_i18n_ctx_get() cannot be called, e.g. constant initializers. The result embeds the context, so translate it later with pbl_i18n_get() rather than pbl_i18n_ctx_get().

Parameters

ctx	Context string literal.
string	String literal.

PBL_I18N_LOCALE_LEN

#define PBL_I18N_LOCALE_LEN   6

Size of an ISO locale string such as "en_US", including the terminator.

PBL_I18N_NAME_LEN

#define PBL_I18N_NAME_LEN   30

Size of a language name buffer, including the terminator.

pbl_i18n_noop

#define pbl_i18n_noop

(

string

)

(string)

Tag a string for extraction without translating it.

For places where pbl_i18n_get() cannot be called, e.g. constant initializers. Translate the string later with pbl_i18n_get().

Parameters

string

String literal.

Function Documentation

pbl_i18n_catalog_get_info()

int pbl_i18n_catalog_get_info	(	const struct pbl_i18n_catalog *	catalog,
		struct pbl_i18n_catalog_info *	info
	)

Read the metadata of a catalog without setting it.

Parameters

	catalog	Catalog, pbl_i18n_catalog::size is not used.
[out]	info	Metadata, with its strings zero-padded.

Returns

0 on success, negative errno otherwise.

pbl_i18n_free()

void pbl_i18n_free	(	const char *	string,
		const void *	owner
	)

Free a cached translation.

Parameters

string	Original string passed to pbl_i18n_get().
owner	Owner passed to pbl_i18n_get(), must not be NULL.

pbl_i18n_free_all()

void pbl_i18n_free_all

(

const void *

owner

)

Free all cached translations of an owner.

Parameters

owner

Owner passed to pbl_i18n_get().

pbl_i18n_get()

const char * pbl_i18n_get	(	const char *	string,
		const void *	owner
	)

Translate a string, caching the result for an owner.

The translation is truncated to 199 characters. There is no reference counting: when the same string is requested several times for the same owner, all returned pointers become invalid once pbl_i18n_free() is called on any of them. Setting a catalog also invalidates them.

Parameters

string	Original string, possibly with a context from pbl_i18n_ctx_noop().
owner	Owner of the cached translation, must not be NULL.

Returns

Translation, or the original string without its context if there is none.

pbl_i18n_get_lang_name()

char * pbl_i18n_get_lang_name

(

void

)

Get the language name of the catalog.

Returns

Language name, "English" when no catalog is set.

pbl_i18n_get_length()

size_t pbl_i18n_get_length

(

const char *

string

)

Get the length of a translated string.

Parameters

string

Original string, possibly with a context from pbl_i18n_ctx_noop().

Returns

Length of the translation without terminator, or of the original if there is none.

pbl_i18n_get_locale()

char * pbl_i18n_get_locale

(

void

)

Get the ISO locale of the catalog.

Returns

Locale such as "fr_FR", "en_US" when no catalog is set.

pbl_i18n_get_version()

uint16_t pbl_i18n_get_version

(

void

)

Get the version of the catalog.

Returns

Catalog version, 1 when no catalog is set.

pbl_i18n_get_with_buffer()

void pbl_i18n_get_with_buffer	(	const char *	string,
		char *	buffer,
		size_t	length
	)

Translate a string into a buffer.

Nothing is cached. The result is truncated to fit and always terminated, unless length is 0.

Parameters

	string	Original string, possibly with a context from pbl_i18n_ctx_noop().
[out]	buffer	Output buffer.
	length	Size of buffer in bytes.

pbl_i18n_set_catalog()

int pbl_i18n_set_catalog

(

const struct pbl_i18n_catalog *

catalog

)

Set the catalog translations come from.

Frees every cached translation, so pointers returned by pbl_i18n_get() become invalid. If the catalog cannot be used no catalog is set. The catalog is copied, but pbl_i18n_catalog::data must stay valid until another catalog is set.

Parameters

catalog

Catalog, NULL for none.

Returns

0 on success, negative errno otherwise.