Internationalization API Guidelines

Core Semantics

source text = built-in English text or format pattern
display text = source text after optional translation
key = dot-separated domain, optional subdomain, and final text name

Primary Types

DisplayTextMap  // keyed source texts, translated results, and compiled-format caches
DisplayTextTranslator  // translation interface for resolved English source text

Secondary Types

DisplayTextMapPtr, DisplayTextMapConstPtr // mutable and immutable shared display-text maps
DisplayTextTranslatorPtr, DisplayTextTranslatorConstPtr // mutable and immutable shared translators

Map Patterns

T()  // create a mutable map populated with built-in English text
T::defaultMap() -> const DisplayTextMapConstPtr&  // immutable process-wide English defaults
o.clone() -> DisplayTextMapPtr  // copy sources and translator without cached results
o.text(key) -> String  // resolve and translate text; return key if it is missing
o.format(key) -> StringFormat  // resolve, translate, compile, and cache a format
o.set(key, text)/remove(key) -> DisplayTextMap&  // edit source text and clear caches
o.translator()/setTranslator(translator)  // access or replace translation behavior

Translator Patterns

o.translate(key, sourceText) -> String  // translate source text; empty keeps the English source