I18n
Namespace: Shadop.Archmage.Sdk
Manages multilingual text with automatic fallback to a default language.
public class I18nRemarks:
I18n (internationalization) stores text for multiple languages and retrieves them on demand. When a text key is not available in the requested language, it automatically falls back to the configured fallback language.
Usage pattern:
- Create an I18n instance with a fallback language
- Load translations via MergeTexts, MergeL10nData, or MergeL10nFile
- Retrieve translations via GetText or Text
Constructors
Section titled “Constructors”I18n(String)
Section titled “I18n(String)”Creates I18n with fallback language (used when key not found in requested language).
public I18n(string fallbackLanguage)Parameters
Section titled “Parameters”fallbackLanguage String
Exceptions
Section titled “Exceptions”ArgumentNullException
Thrown if fallbackLanguage is null.
Methods
Section titled “Methods”Fallback()
Section titled “Fallback()”Gets the fallback language code.
public string Fallback()Returns
Section titled “Returns”AllTexts()
Section titled “AllTexts()”Returns the internal translation structure: language → (key → text). Modifications to the returned dictionary will affect future lookups.
public Dictionary<string, Dictionary<string, string>> AllTexts()Returns
Section titled “Returns”Dictionary<String, Dictionary<String, String>>
MergeTexts(Dictionary<String, String>, String)
Section titled “MergeTexts(Dictionary<String, String>, String)”Merges translation key-value pairs for a specific language. Creates the language entry if it doesn’t exist; overwrites existing keys.
public void MergeTexts(Dictionary<string, string> texts, string language)Parameters
Section titled “Parameters”texts Dictionary<String, String>
Dictionary of translation key-value pairs.
language String
The language code to merge into.
MergeL10nData(Byte[], String)
Section titled “MergeL10nData(Byte[], String)”Parses JSON bytes (flat object) and merges translations for the specified language.
public void MergeL10nData(Byte[] data, string language)Parameters
Section titled “Parameters”data Byte[]
UTF-8 encoded JSON bytes of a flat object.
language String
The language code to merge into.
Exceptions
Section titled “Exceptions”T:Newtonsoft.Json.JsonException
Thrown if JSON parsing fails.
MergeL10nFile(String, String, IFS)
Section titled “MergeL10nFile(String, String, IFS)”Loads a localization JSON file and merges translations for the specified language.
public void MergeL10nFile(string filePath, string language, IFS fs)Parameters
Section titled “Parameters”filePath String
Path to the JSON file (flat object with string keys/values).
language String
The language code to merge into.
fs IFS
Optional file system abstraction; defaults to File.ReadAllBytes(String) if null.
Exceptions
Section titled “Exceptions”ArchmageException
Thrown if reading the file or parsing JSON fails.
MergeL10nFileAsync(String, String, IFS, CancellationToken)
Section titled “MergeL10nFileAsync(String, String, IFS, CancellationToken)”Asynchronously loads a localization JSON file and merges translations for the specified language.
public Task MergeL10nFileAsync(string filePath, string language, IFS fs, CancellationToken cancellationToken)Parameters
Section titled “Parameters”filePath String
Path to the JSON file (flat object with string keys/values).
language String
The language code to merge into.
fs IFS
Optional file system abstraction; defaults to File.ReadAllBytesAsync(String, CancellationToken) if null.
cancellationToken CancellationToken
Token to cancel the operation.
Returns
Section titled “Returns”Exceptions
Section titled “Exceptions”ArchmageException
Thrown if reading the file or parsing JSON fails.
GetText(String, String, String&)
Section titled “GetText(String, String, String&)”Attempts to retrieve text with fallback. Tries the requested language first, then falls back to the default language.
public bool GetText(string key, string language, String& text)Parameters
Section titled “Parameters”key String
The translation key.
language String
The preferred language code.
text String&
The retrieved text, or null if not found.
Returns
Section titled “Returns”Boolean
True if the key was found in either the requested or fallback language; otherwise, false.
Text(String, String)
Section titled “Text(String, String)”Retrieves text with fallback, throwing an exception if not found. Tries the requested language first, then falls back to the default language.
public string Text(string key, string language)Parameters
Section titled “Parameters”key String
The translation key.
language String
The preferred language code.
Returns
Section titled “Returns”String
The translation string.
Exceptions
Section titled “Exceptions”ArchmageException
Thrown if the key is not found in either the requested or fallback language.