i18n.text

This library aims to facilitate native language support in applications and libraries written in D. String resources containing natural language text are read from XML documents, called catalogs, supplied at compile-time. In source code, string resources are referenced with the strings interface. The languages to use are configured automatically at the start of the program based on the running user's environment, before the main function is entered.

Catalogs

There are two kinds of catalogs: the singular primary catalog and one translation catalog for each translation. Each catalog is an XML * document made visible to the framework as a string import.

Primary Catalog

The primary catalog is loaded from the string import i18n/strings.xml and specifies the primary table of string resources, which is used when:

• The language of the primary table matches that of the user's preferred language
• A translation catalog for the user's preferred language is not supplied
• A translation catalog for the user's preferred language is supplied, but does not contain a translation for the particular string being looked up
• Internationalization is disabled

The primary catalog must have the following structure:

$(LESS)?xml version="1.0" encoding="utf-8"?$(GREATER)
$(LESS)resources language="primary_catalog_language"$(GREATER)
	$(LESS)translation language="translation1"/$(GREATER)
	$(LESS)translation language="translation2"/$(GREATER)
	$(LESS)translation language="..."/$(GREATER)
	$(LESS)string name="id1"$(GREATER)text1$(LESS)/string$(GREATER)
	$(LESS)string name="id2"$(GREATER)text2$(LESS)/string$(GREATER)
	$(LESS)string name="..."$(GREATER)...$(LESS)/string$(GREATER)
$(LESS)/resources$(GREATER)

For the primary catalog, the root element's language attribute is required and contains the language used in the primary catalog. Each translation element declares that a translation catalog for the given language is supplied and should be loaded. All language attributes are ISO-639 language codes. Each string element defines a string resource, where the name attribute is the resource identifier, and the element's content is the resource text.

Translation Catalogs

Translation catalogs are loaded as string imports from i18n/strings.$(I ll).xml where $(I ll) is the ISO-639 language code for the language translation provided within the document. Each translation must be enumerated in the primary catalog with the translation tag.

The structure of translation catalogs is a subset of the structure of the primary catalog:

$(LESS)?xml version="1.0" encoding="utf-8"?$(GREATER)
$(LESS)resources$(GREATER)
	$(LESS)string name="id1"$(GREATER)text1$(LESS)/string$(GREATER)
	$(LESS)string name="id2"$(GREATER)text2$(LESS)/string$(GREATER)
	$(LESS)string name="..."$(GREATER)...$(LESS)/string$(GREATER)
$(LESS)/resources$(GREATER)

Each string element provides a translation of the string resource with the given identifier. The identifier must match the identifier of a string resource in the primary catalog.

String References

In source code, string resources are referenced with the strings interface:

void main() {
    import std.stdio, i18n.text;
    // Writes the string resource with the identifier "hello_world" to stdout
    writeln(strings.hello_world);
}

Language Selection

Platform-specific standards are used for selecting the preferred language. On POSIX systems, this is the POSIX standard of using environment variables, including the fallback/priority syntax supported by gettext. See gettext's documentation on setting the POSIX locale.

Version Identifiers

The behavior of this module can be configured with version identifiers.

• i18n_list_references: source code locations of string references will be output during compilation
• i18n_use_utf32: string resources are encoded in UTF-32 by default
• i18n_use_utf16: string resources are encoded in UTF-16 by default