lynMarkdigRenderTest74 1.0.0

Localization

Lexical.Util.Localization is a localization class that reads localization strings with Microsoft.Extensions.Configuration.IConfiguration interface.

• Website
• Github

Construction

Localization is the base class that contains strings, configurations, resolvers. LocalizationKeys can be created from Localization.

There is also a singleton instance Localization.Instance.

// Use singleton instance
Localization localization = Localization.Instance;

Populating strings

Localization strings are added with Localization.Builder which is an IConfigurationBuilder.

Memory strings

Static strings are added with instances of MemoryConfigurationSource. There is an extension method AddInMemoryCollection that wraps it from IEnumeration argument.

// Populate hardcoded localization strings
Dictionary<string, string> defaultStrings = new Dictionary<string, string>();
defaultStrings["en:ConsoleApp1:MyController:Success"] = "Success";
defaultStrings["en:ConsoleApp1:MyController:Error"] = "Error (Code=0x{0:X8})";
defaultStrings["fi:ConsoleApp1:MyController:Success"] = "Onnistui";
defaultStrings["fi:ConsoleApp1:MyController:Error"] = "Virhe (Koodi=0x{0:X8})";
defaultStrings["fi-SAVO:ConsoleApp1:MyController:Success"] = "Onnistuepa";
defaultStrings["fi-SAVO:ConsoleApp1:MyController:Error"] = "Epäonnistuepa (Koodi=0x{0:X8})";
Localization.Instance.Builder.AddInMemoryCollection(defaultStrings);

// Build after IConfigurationSources are added
Localization.Instance.Rebuild();

Ini strings

Json strings are added with instances of IniConfigurationSource.

Possible locations of .ini files must be given with file providers:

• EmbeddedFileProvider
• PhysicalFileProvider
• CompositeFileProvider

There is an extension method AddIniFile that adds ini files.

// Populate localization.ini
Assembly assembly = Assembly.GetExecutingAssembly();
String installDir = Path.GetDirectoryName(new Uri(assembly.CodeBase).AbsolutePath);
IFileProvider fileProvider = new PhysicalFileProvider(installDir);
IFileProvider embedded = new EmbeddedFileProvider(assembly);
IFileProvider composite = new CompositeFileProvider(fileProvider, embedded);
Localization.Instance.Builder.SetFileProvider(composite);
Localization.Instance.Builder.AddIniFile("localization.ini", optional: true, reloadOnChange: false);

// Build after IConfigurationSources are added
Localization.Instance.Rebuild();

Example localization.ini

[en]
ConsoleApp1:MyController:Success      = Success
ConsoleApp1:MyController:Error        = Error (Code=0x{0:X8})

[fi]
ConsoleApp1:MyController:Success      = Onnistui
ConsoleApp1:MyController:Error        = Virhe (Koodi=0x{0:X8})

[fi-SAVO]
ConsoleApp1:MyController:Success = Onnistuepa
ConsoleApp1:MyController:Error   = Epäonnistuepa (Koodi=0x{0:X8})

Json strings

Json strings are added with instances of JsonConfigurationSource.

There is an extension method AddIniFile that adds json files.

Inlined strings

Language strings can be inlined right into the code.

At run-time.

// Inline string
dynamic myLocalization = new Localization();
Console.WriteLine(
    myLocalization.ConsoleApp1.MyController.Success
    .Inline("fi", "Onnistui")
    .Inline("en", "Success")
);

// Note that inlined strings must be compiled into .ini file with Lexical.Utils.Localization.Scanner.exe

And at compile-time.

// Inline string
Localization myLocalization = new Localization();
Console.WriteLine(
    myLocalization["ConsoleApp1:MyController:Success"]
    .Inline("fi", "Onnistui")
    .Inline("en", "Success")
);

// Note that inlined strings must be compiled into .ini file with Lexical.Utils.Localization.Scanner.exe

Inlined LocalizationKeys, however, work only from the very instance the Inline() is called to, unless those calls are scanned and canned into an .ini file. There is a tool that does just that Lexical.Utils.Localization.Scanner.exe. This tool must be activated from a T4 Text Templating script: localization_inlined.tt.

Dynamic use

Keys can be constructed and resolved dynamically.

// Resolve keys to current culture
Console.WriteLine(Localization.Dynamic.ConsoleApp1.MyController.Success);
Console.WriteLine(Localization.Dynamic.ConsoleApp1.MyController.Error);

And to specific cultures.

// Resolve key to specific culture
Console.WriteLine(Localization.Dynamic.fi.ConsoleApp1.MyController.Success);
Console.WriteLine(Localization.Dynamic.en.ConsoleApp1.MyController.Success);

Get the key identity.

// Retrieve the key, but do not resolve
Console.WriteLine(Localization.Dynamic.fi.ConsoleApp1.MyController.Success.Name);

Formulate with arguments.

// Format key with arguments
Console.WriteLine(Localization.Dynamic.ConsoleApp1.MyController.Error.Format(0xBAADF00D));

Key construction.

// Construct key dynamically
LocalizationKey key1 = Localization.Dynamic.ConsoleApp1.MyController.Error;
Console.WriteLine(key1.Name);
Console.WriteLine(key1.ToString());

Static use

Keys can be constructed and resolved.

// Resolve statically to current culture
Console.WriteLine(Localization.Instance["ConsoleApp1:MyController:Success"]);

And to specific cultures.

// Resolve statically to specific cultures
Console.WriteLine(Localization.Instance["en:ConsoleApp1:MyController:Success"]);
Console.WriteLine(Localization.Instance["fi:ConsoleApp1:MyController:Success"]);

Get the key identity.

// Retrieve the key, but do not resolve
Console.WriteLine(Localization.Instance["ConsoleApp1:MyController:Success"].Name);

Formulate with arguments.

// Format key with arguments
Console.WriteLine(Localization.Instance["fi:ConsoleApp1:MyController:Error"].Format(0xBAADF00D));
Console.WriteLine(Localization.Instance["en:ConsoleApp1:MyController:Error"].Format(0xBAADF00D));

Use in classes

namespace ConsoleApp1
{
    public class MyController
    {
        // Take localization branch for this class "ConsoleApp1:MyController"
        static dynamic localization = Localization.Instance.ForType<MyController>();

        // Take reference for key "ConsoleApp1:MyController:Unknown", faster usage
        static LocalizationKey unknown = localization.Unknown.Inline("en", "Uncertain result (Code=0x{0:X8})");

        public void DoAction1()
        {
            // Take key with dynamic accessor and resolve message
            Console.WriteLine(localization.Success.Inline("en", "Success"));
        }

        public void DoAction2()
        {
            // Format message with dynamic accessor
            Console.WriteLine(localization.Error.Inline("en", "Error (Code=0x{0:X8})").Format(0xCafeD00d));
        }

        public void DoAction3()
        {
            // Format message with static reference
            Console.WriteLine(unknown.Format(0xFEEDF00D));
        }
    }
}