Localized Strings

A Localized String is a reference to a string in the strings table of a locale. It can be used in lieu of a string variable to refer to a localized value.

Defining localized strings in components

Localized strings can be defined on components or scriptable objects using a serialized LocalizedString variable. The inspector provides a convenient interface to select a path from the list of loaded locales, or to enter a non-localized value. In this sense it replaces a string variable where you would usually enter displayed text.

In general a localized string is referred to as its interface ILocalizedString in code, but because Unity cannot serialize interfaces in components, you have to use the LocalizedString class whenever you want to serialize a localized string.

Defining and modifying localized strings in code

To create new localized strings in code, the following methods on the ILocalizedString interface can be used:

• ILocalizedString.Empty(): Creates an empty string.
• ILocalizedString.Path(string path): Creates a string that points to path in the strings table of a locale.
• ILocalizedString.Value(string value): Creates a string with the non-localized value value.
• ILocalizedString.Function(string name, string argument = null): Creates a string that executes the function name with the optional argument argument.
• ILocalizedString.Asset(string path): Creates a string that prints the contents of a text asset in a Resources folder at path, akin to LocalizationSystem.current.FormatAsset(string path).

The formatted value of a localized string can be mapped using the following method on a ILocalizedString instance:

• Select(Func<string, string> selector>) Maps the formatted value of a localized string using the function selector when formatting the string.

Strings can also be concatenated and joined using the following static methods on the ILocalizedString interface:

• Join(ILocalizedString separator, IEnumerable<ILocalizedString> strings): Joins the localized strings strings by putting separator between every string.
• Join(string separator, IEnumerable<ILocalizedString> strings): More convenient Join method where separator is a non-localized value.
• Concat(IEnumerable<ILocalizedString> strings): Concatenates the localized strings strings; equivalent to Join("", strings).
• Concat(params ILocalizedString[] strings): More convenient Concat method where strings can be specified as method arguments.
• ILocalizedString left + ILocalizedString right: The Concat method as an operator for easy concatenating. Also works with strings as either operand.

Setting Arguments

To set an argument that is defined in a string, the following methods on a ILocalizedString instance can be used:

• WithArgument(string key, object value): Sets the argument key to object value.
• WithArguments(IReadOnlyDictionary<string, object> arguments): Sets all arguments defined in the dictionary arguments. This is more performant than chaining multiple WithArgument(...) calls.
• WithArguments(ILocalizedStringArgumentsProvider provider): Set all arguments from the arguments property of the object provider that implements the ILocalizedStringArgumentsProvider interface.

All of the above methods return a new ILocalizedString instance for chainability.

Example of setting an argument

void SetArgument()
{
	// Assume the "damage" string is defined as "Does {amount} damage to enemies"
	var localizedString = ILocalizedString.Path("damage")
	    .WithArgument("amount", 20);
	
	// Text will be equal to "Does 20 damage to enemies"
	var text = LocalizationSystem.current.Format(localizedString);
}

Example of setting arguments from a provider interface

class Perk : ILocalizedStringArgumentsProvider
{
	// Variables of the perk
	public int damage;
	public int criticalHitChance;
	
	// Arguments of the perk will be define dhere
	public IReadOnlyDictionary<string, object> arguments 
		=> new Dictionary<string, object>() {
			{ "damage", damage },
			{ "criticalHitChance", criticalHitChance },
		}
}

void SetArgumentsFromProvider()
{
	var perk = new Perk { damage = 20, criticalHitChance = 0.25 };
	
	// Assume the "damage" string is defined as "Does {amount} damage to enemies"
	var localizedString = ILocalizedString.Path("damage")
	    .WithArguments(perk);
	
	// Text will be equal to "Does 20 damage to enemies"
	var text = LocalizationSystem.current.Format(localizedString);
}

Formatting using the localization system

To format a localized string in code, the following methods on the LocalizationSystem.current instance can be used:

• LocalizationSystem.current.Format(ILocalizedString reference): Formats the localized string reference using the selected locale of the system.
• LocalizationSystem.current.Format(string message, IReadOnlyDictionary<string, object> arguments = null): Formats the raw string message with the arguments arguments using the selected locale of the system.
• LocalizationSystem.current.FormatAsset(string path, IReadOnlyDictionary<string, object> arguments = null): Formats the contents of a text asset in a Resources folder at path with the arguments arguments using the selected locale of the system.
• LocalizationSystem.current.FormatFile(string path, Encoding encoding, IReadOnlyDictionary<string, object> arguments = null): Formats the contents of a file on the file system at path with encoding encoding and the arguments arguments using the selected locale of the system.

Those four methods also have variants that take a Locale arguments as first argument next to the other arguments to format using that locale instead of the selected locale.

Example of formatting a localized string

void Format()
{
	// Assume the "play" string is defined as "Play Game"
	var localizedString = ILocalizedString.Path("play");
	
	// Text will be equal to "Play Game"
	var text = LocalizationSystem.current.Format(localizedString);
}

Localized string explorer

The localization package comes with a localized string explorer that can be opened from the Tools > Audune Localization > Localized String Explorer menu or the Ctrl+Shift+Alt+S keyboard shortcut. From here the Unity project will be scanned for all localized string fields.

If you double click on a localized string or use the Show Component context menu option, Unity will open the respective prefab, scriptable object, or scene, and navigate to the component where the localized string is defined. Use the Find Definition context menu option to open the locale explorer and show the string definition for the localized string.