i18n-d

Github Page

i18n-d

Text translation framework.

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: 
<?xml version="1.0" encoding="utf-8"?>
<resources language="primary_catalog_language">
	<translation language="translation1"/>
	<translation language="translation2"/>
	<translation language="..."/>
	<string name="id1">text1</string>
	<string name="id2">text2</string>
	<string name="...">...</string>
</resources>
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.ll.xml where 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: 
<?xml version="1.0" encoding="utf-8"?>
<resources>
	<string name="id1">text1</string>
	<string name="id2">text2</string>
	<string name="...">...</string>
</resources>
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

See Also
gettext's advice on separating strings and translating proper names

struct  Strings();



static pure nothrow @nogc @safe bool  identifierExists(string id);

Returns
true iff id is defined in the primary catalog
Complexity:
Ο(log n)

alias  I18NString = string;

Default encoding for string resources, returned by Strings.opDispatch.

Set version i18n_use_utf32 to use dstring, or version i18n_use_utf16 to use wstring; otherwise uses string (UTF-8).

pure nothrow @nogc @property @safe I18NString  opDispatch(string id)() if (identifierExists(id));
pure nothrow @nogc @safe S  getEncoded(string id, S)() if (identifierExists(id));

Get the text for id according to the user's preferred language(s).

Parameters
id identifier of string resource (the name attribute)
S encoding for returned string, either string, wstring or dstring
Complexity:
Ο(1). The upper bound is proportional to the number of translations provided at compile-time. The number of string resources does not affect runtime.
Example:
void main()
{
    import std.stdio, i18n.text;
    writeln(strings.hello_world); // Default encoding
    writeln(strings.getEncoded!("hello_world", wstring)); // UTF-16
}

pure nothrow @nogc @property @safe Strings!()  strings()();

See Also
Strings