Internationalization

Translates firmware strings with the installed language pack. More...

Modules
	MO file format
	Layout of gettext MO files, used for language packs.

Data Structures
struct	I18nString
	Cached translation, stored in a list per language pack. More...

Macros
#define	ISO_LOCALE_LENGTH   6
	Size of an ISO locale string such as "en_US", including the terminator.
#define	LOCALE_NAME_LENGTH   30
	Size of a language name buffer, including the terminator.
#define	i18n_noop(string)   (string)
	Tag a string for extraction without translating it.
#define	i18n_ctx_noop(ctx, string)   (ctx "\4" string)
	Tag a string with a context for extraction without translating it.
#define	i18n_ctx_get(ctx, string, owner)   i18n_get(i18n_ctx_noop(ctx, string), owner)
	i18n_get() with a context.
#define	i18n_ctx_get_with_buffer(ctx, string, buffer, length)    i18n_get_with_buffer(i18n_ctx_noop(ctx, string), buffer, length)
	i18n_get_with_buffer() with a context.
#define	i18n_ctx_get_length(ctx, string)   i18n_get_length(i18n_ctx_noop(ctx, string))
	i18n_get_length() with a context.
#define	i18n_ctx_free(ctx, string, owner)   i18n_free(i18n_ctx_noop(ctx, string), owner)
	i18n_free() with a context.

Functions
const char *	i18n_get (const char *string, const void *owner)
	Translate a string, caching the result for an owner.
void	i18n_get_with_buffer (const char *string, char *buffer, size_t length)
	Translate a string into a buffer.
size_t	i18n_get_length (const char *string)
	Get the length of a translated string.
void	i18n_free (const char *string, const void *owner)
	Free a cached translation.
void	i18n_free_all (const void *owner)
	Free all cached translations of an owner.
void	i18n_set_resource (uint32_t resource_id)
	Select the system resource holding the language pack.
char *	i18n_get_locale (void)
	Get the ISO locale of the installed language.
uint16_t	i18n_get_version (void)
	Get the version of the installed language pack.
char *	i18n_get_lang_name (void)
	Get the name of the installed language.
void	i18n_enable (bool enable)
	Load or unload the language pack.

Detailed Description

Translates firmware strings with the installed language pack.

The language pack is a gettext MO file stored as a system resource. Strings are looked up by their English original (the msgid); when no translation exists, or no language pack is installed, the original is returned. A context can be attached to disambiguate identical originals with the _ctx_ variants. Mark strings with i18n_noop() or i18n_ctx_noop() where they cannot be translated in place, so they are still extracted for translation. Changing the language puts a PEBBLE_LANGUAGE_CHANGE_EVENT.

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

text_layer_set_text(&data->title, i18n_get("Settings", data));
...
i18n_free_all(data);

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

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

---

Data Structure Documentation

I18nString

struct I18nString

Cached translation, stored in a list per language pack.

Data Fields
ListNode	node	Linked list node.
uint32_t	original_hash	Hash of the original string.
char *	original_string	Original string, stored right after translated_string.
const void *	owner	Owner the translation was requested for.
char	translated_string[]	Translated string, followed by the storage of the original string.

Macro Definition Documentation

i18n_ctx_free

#define i18n_ctx_free	(		ctx,
			string,
			owner
	)		i18n_free(i18n_ctx_noop(ctx, string), owner)

i18n_free() with a context.

Parameters

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

i18n_ctx_get

#define i18n_ctx_get	(		ctx,
			string,
			owner
	)		i18n_get(i18n_ctx_noop(ctx, string), owner)

i18n_get() with a context.

Parameters

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

i18n_ctx_get_length

#define i18n_ctx_get_length	(		ctx,
			string
	)		i18n_get_length(i18n_ctx_noop(ctx, string))

i18n_get_length() with a context.

Parameters

ctx	Context string literal.
string	Original string literal.

i18n_ctx_get_with_buffer

#define i18n_ctx_get_with_buffer	(		ctx,
			string,
			buffer,
			length
	)		i18n_get_with_buffer(i18n_ctx_noop(ctx, string), buffer, length)

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.

i18n_ctx_noop

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

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

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

Parameters

ctx	Context string literal.
string	String literal.

i18n_noop

#define i18n_noop

(

string

)

(string)

Tag a string for extraction without translating it.

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

Parameters

string

String literal.

ISO_LOCALE_LENGTH

#define ISO_LOCALE_LENGTH   6

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

LOCALE_NAME_LENGTH

#define LOCALE_NAME_LENGTH   30

Size of a language name buffer, including the terminator.

Function Documentation

i18n_enable()

void i18n_enable

(

bool

enable

)

Load or unload the language pack.

Parameters

enable

true to load the language pack, false to fall back to English.

i18n_free()

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

Free a cached translation.

Parameters

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

i18n_free_all()

void i18n_free_all

(

const void *

owner

)

Free all cached translations of an owner.

Parameters

owner

Owner passed to i18n_get().

i18n_get()

const char * 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 i18n_free() is called on any of them. A language change also invalidates them.

Parameters

string	Original string, possibly with a context from 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.

i18n_get_lang_name()

char * i18n_get_lang_name

(

void

)

Get the name of the installed language.

Returns

Language name, "English" when no language pack is loaded.

i18n_get_length()

size_t i18n_get_length

(

const char *

string

)

Get the length of a translated string.

Parameters

string

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

Returns

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

i18n_get_locale()

char * i18n_get_locale

(

void

)

Get the ISO locale of the installed language.

Returns

Locale such as "en_US", "en_US" when no language pack is loaded.

i18n_get_version()

uint16_t i18n_get_version

(

void

)

Get the version of the installed language pack.

Returns

Language pack version, 1 when none is loaded.

i18n_get_with_buffer()

void 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 i18n_ctx_noop().
[out]	buffer	Output buffer.
	length	Size of buffer in bytes.

i18n_set_resource()

void i18n_set_resource

(

uint32_t

resource_id

)

Select the system resource holding the language pack.

The resource is watched, so installing a new language pack reloads it. If the user chose English, the language pack is not loaded.

Parameters

resource_id

System resource ID of the language pack.