Internationalization API Guidelines

Core Semantics

source text = compiled English text or format pattern
display text = resolved source text after optional translation
key = normalized ELCL names separated by dots
layer = one immutable DisplayTextData instance registered by object identity

Primary Types

DisplayText  // application-owned registry, translations, and compiled-format caches
DisplayTextData  // immutable sorted domain/entry arrays with exact binary lookup
DisplayTextTranslator  // translation interface for resolved English source text

Secondary Types

DisplayTextPtr, DisplayTextConstPtr // shared registry interface
DisplayTextDataPtr, DisplayTextDataConstPtr // shared immutable catalog data
DisplayTextTranslatorPtr, DisplayTextTranslatorConstPtr // shared translators

Registry Patterns

application().displayText() -> DisplayTextPtr // access the application-owned registry
o.text(key) -> String // resolve and translate; return the requested key if missing
o.format(key) -> StringFormat // resolve, translate, compile, and cache
o.addData(data) // register a new top layer; duplicate identity leaves ordering unchanged
o.removeData(data) -> bool // remove an application layer; preserve the built-in bottom layer
o.translator()/setTranslator(translator) // access or replace translation behavior
displayText(key) -> String // resolve through the application registry
displayFormat(key) -> StringFormat // resolve a format through the application registry

Data Patterns

o.domains() -> span<const impl::DisplayTextDomain> // immutable sorted domains and entries
o.findText(key) -> optional<String> // exact source lookup without translation or fallback
T::create() -> DisplayTextDataPtr // share permanent generated backing arrays

Translator Patterns

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