Skip to content

Game.UI.Localization.LocalizedString

Assembly:
Assembly-CSharp (game)

Namespace:
Game.UI.Localization

Type:
readonly struct LocalizedString

Base:
System.ValueType
Implements: ILocElement, IJsonWritable, IEquatable

Summary:
Represents an immutable localized text entry used by the UI localization system. A LocalizedString can refer to a localization entry by id, provide a fallback literal value, and carry formatting arguments (as a read-only dictionary of ILocElement). It supports JSON writing via IJsonWritable, value equality, and an implicit conversion from string (treating the string as an id). Nullability annotations are used: id, value and args may be null.

Fields

  • This struct does not declare any private fields. It exposes its data via read-only properties (id, value, args, isEmpty).
    {{ The data is stored in auto-properties (readonly getters). There are no explicit backing fields visible in the source. }}

Properties

  • public string id { get; }
    {{ The localization identifier. Nullable: when non-null this indicates the string should be resolved through the localization system. If non-null, isEmpty always returns false. }}

  • public string value { get; }
    {{ A literal fallback value for the string (nullable). Used when id is null or as a fallback if lookup by id fails (depending on usage). }}

  • public IReadOnlyDictionary<string, ILocElement> args { get; }
    {{ Optional formatting arguments for the localized text. Keys are argument names and values are ILocElement instances that will be used by formatting/rendering code. Nullable. }}

  • public bool isEmpty { get; }
    {{ True when both id and value are null; false otherwise. Note: if id is non-null, isEmpty returns false even when value is null. }}

Constructors

  • public LocalizedString(string id, string value, IReadOnlyDictionary<string, ILocElement> args)
    {{ Creates a LocalizedString with the given id, fallback value, and argument dictionary. Any of the parameters may be null to represent absence. Typical usage patterns are to provide either an id (for localized lookup) or a value (for literal text). }}

  • public static LocalizedString Id(string id)
    {{ Factory helper that constructs a LocalizedString with the supplied id and null value/args. Equivalent to new LocalizedString(id, null, null). }}

  • public static LocalizedString Value(string value)
    {{ Factory helper that constructs a LocalizedString using a literal value with null id and args. Equivalent to new LocalizedString(null, value, null). }}

  • public static LocalizedString IdWithFallback(string id, string value)
    {{ Factory helper that sets both an id and a fallback value. Equivalent to new LocalizedString(id, value, null). }}

Methods

  • public void Write(IJsonWriter writer)
    {{ Writes the LocalizedString into the given IJsonWriter. The implementation writes a type begin using the runtime type name, then writes the properties "id", "value", and "args", and finally ends the type. This is used for serialization/debugging via the game's JSON writer interface. }}

  • public bool Equals(LocalizedString other)
    {{ Value equality check: returns true when both id and value are equal and the args dictionaries are considered equal (see ArgsEqual). Uses string equality for id/value. }}

  • private static bool ArgsEqual(IReadOnlyDictionary<string, ILocElement> a, IReadOnlyDictionary<string, ILocElement> b)
    {{ Compares the two argument dictionaries. If the references are equal, returns true. If both non-null, performs a sequence equality comparison (SequenceEqual) which compares key/value pairs. Returns false if one is null and the other is not. }}

  • public override bool Equals(object obj)
    {{ Overrides Object.Equals: returns true when obj is a LocalizedString that equals this instance. }}

  • public override int GetHashCode()
    {{ Computes a combined hash code of id, value, and args using HashCode.Combine. }}

  • public static implicit operator LocalizedString(string id)
    {{ Implicit conversion from string to LocalizedString: treats the string as an id (calls Id(id)). This allows passing a plain string where a LocalizedString is expected to mean a lookup by id. }}

Usage Example

// Treat a string literal as a localization id (implicit conversion)
LocalizedString title = "GAME_TITLE"; // equivalent to LocalizedString.Id("GAME_TITLE")

// Create a localized string from a literal value (no lookup)
LocalizedString plain = LocalizedString.Value("Welcome to my city!");

// Id with a fallback value (lookup with fallback)
LocalizedString withFallback = LocalizedString.IdWithFallback("MAIN_MENU_WELCOME", "Welcome!");

// With formatting arguments (args values implement ILocElement)
var args = new Dictionary<string, ILocElement>
{
    { "playerName", LocalizedString.Value("Mayor") },
    { "cityName", LocalizedString.Value("New Town") }
};
LocalizedString formatted = new LocalizedString("CITY_GREETING", null, args);

// Equality check
bool same = formatted.Equals(new LocalizedString("CITY_GREETING", null, args));

// Serializing to JSON via IJsonWriter (writer implementation provided by the game)
IJsonWriter writer = /* obtain writer from environment */;
formatted.Write(writer);

{{ Notes: - Use the Id(...) factory or implicit string conversion when you want the localization system to look up the text. - Use Value(...) when you have a literal string that should not be localized. - Pass args to supply dynamic sub-values for formatted localization entries; values are ILocElement so they can themselves be LocalizedString or other loc elements. - isEmpty is true only when both id and value are null; otherwise the LocalizedString represents something usable. }}