***********************************
Internationalization API Guidelines
***********************************

Core Semantics
==============

.. code-block:: text

    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
=============

.. code-block:: text

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

Secondary Types
===============

.. code-block:: text

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

Map Patterns
============

.. code-block:: text

    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
===================

.. code-block:: text

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