Nittin.Localizator 1.1.1

Nittin.Localizations

Localization creating tool

This project contains class library which allows the developer to create and use localizations and is meant to simplify the process of creating, setting and using localizations. The project uses decorator pattern to mark localizeable classes and properties of a localizeable class and reflections to find and use these localizations.

Main use case

This is mostly meant to simplify process of creating many localization texts in Kentico cms application and makes sense for versions of Kentico which use the concept of localizations. Localizations are a time consuming process where the developer has to Start the cms administration, create a localization, create it's name and than copy this name to code and use a static string value inside code. This takes up a lot of time of a developer.

Examples

Using localizations

Localizeable attribute

First create a class with <code>Localizeable</code> attribute. This is optional, however this attribute is used to specify the prefix of the localization key. The attribute also has optional parameter <code>string localizationKey</code> which overrides the prefix. If the attribute is used without the parameter the prefix is equal to the name of the class. If the parameter is specified, the prefix is overriden by the value of the parameter.

[Localizeable]
public class BannerWidgetModel
{
    public string ImagePath { get; set; }

    [Localize("This is default text")]
    public string Text { get; set; }

    [Localize]
    public string LinkTitle { get; set; }

    public string LinkUrl { get; set; }

Localize attribute

This attribute is used to specify that the property of a class is localized. This attribute is neccesary in order to be used by the api. The localization key than either consists of the name of this property or can be overriden by setting the <code>localizationKey</code> property. The <code>defaultValue</code> is an optional which can be used to specify the value which should be added to the localization string on creation and also be used if the localization value is null or empty.

[Localizeable]
public class BannerWidgetModel
{
    public string ImagePath { get; set; }

    [Localize("This is default text")]
    public string Text { get; set; }

    [Localize]
    public string LinkTitle { get; set; }

    public string LinkUrl { get; set; }

Looking again at the usage we can see how both of the attributes are used. The localization key will consist of the class's and property's name and this value is then sufixed with ".text". Whole localization key for the Text property will be: BannerWidgetModel.Text.text and it's default value will be "This is default text"

To use this class we can create a generic class which inherits the AspNetCore.Mvc.ViewComponent

public abstract class LocalizationViewComponent<T> : ViewComponent where T : new()
{
    private readonly ILocalizationService _localizationService;
    private readonly Localizator<T> _localizator;

    public LocalizationViewComponent(ILocalizationService localizationService)
    {
        _localizationService = localizationService;
        _localizator = new Localizator<T>();
    }

    public T Localize(bool allowDefault = false)
    {
        return _localizator.Localize((string localizationKey, string defaultValue)
            => GetLocalizationValue(localizationKey, defaultValue, allowDefault)
            );
    }

    protected string GetLocalizationValue(string localizationKey, string? defaultValue = null, bool allowDefault = false, string? culture = null)
    {
        string result = _localizationService.GetString(localizationKey, culture, false);

        if (allowDefault && string.IsNullOrEmpty(result))
        {
            return defaultValue ?? string.Empty;
        }
        return result;
    }
}

Here we are using <code>Localizator<T></code> class which is defined in the library and <code>ILocalizationService</code> which comes from the Kentico api.

We define a <code>T Localize</code> method which calls the Localize method on the localizator and we also need to pass a <code>func<string,string,string></code> which is used by the api to get the localization. This is typically a method which may already be often called to retrieve a value by it's key. In this case we use the instance of <code>ILocalizationService</code>.

This can be then used as follows:

public class BannerWidgetViewComponent : LocalizationViewComponent<BannerWidgetModel>
{
public BannerWidgetViewComponent(ILocalizationService localizationService) : base(localizationService)
{

}

public ViewViewComponentResult Invoke(BannerWidgetProperties properties)
{
    var model = Localize(allowDefault: true);

    model.LinkUrl = properties.LinkUrl;

    return View("~/Components/Widgets/BannerWidget/_BannerWidget.cshtml", model);
}
}

We create a ViewComponent which inherits from our LocalizationViewComponent class. We pass a required service inside a constructor to the base constructor. Then we simply call <code>Localize()</code> method while optionally specifying <code>bool allowDefault</code> to allow the default values specified by the decorators.

All properties with the <code>Localize</code> decorator are localized and we get the object of the class specified by the generic parameter of <code>LocalizationViewComponent</code>.

Then we can specify other properties and use this ViewComponent.

We can also use this more generally for example inside a controller by creating and using the following class:

public class LocalizationComponent<T> where T : new()
{
    private readonly ILocalizationService _localizationService;
    private readonly Localizator<T> _localizator;

    public LocalizationComponent(ILocalizationService localizationService)
    {
        _localizationService = localizationService;
        _localizator = new Localizator<T>();
    }

    public T Localize(bool allowDefault = false)
    {
        return _localizator.Localize((string localizationKey, string defaultValue)
            => GetLocalizationValue(localizationKey, defaultValue, allowDefault)
            );
    }

    protected string GetLocalizationValue(string localizationKey, string? defaultValue = null, bool allowDefault = false, string ? culture = null)
    {
        string result = _localizationService.GetString(localizationKey, culture, false);

        if (allowDefault && string.IsNullOrEmpty(result))
        {
            return defaultValue ?? string.Empty;
        }
        return result;
    }
}

Creating Localizations

The second functionality offered by the api is an option to easily create the localizations.

var localizationCreator = new LocalizationCreator<T>();

localizationCreator.CreateLocalizations((string localizationKey, string defaultValue) =>
{
    var resourceStringInfo = resourceStringInfoProvider.Get(localizationKey);

    if (resourceStringInfo == null)
    {
        resourceStringInfo = new ResourceStringInfo()
        {
            TranslationText = defaultValue,
            StringKey = localizationKey,
            StringIsCustom = true
        };

        resourceStringInfoProvider.Set(resourceStringInfo);
        resourceTranslationInfoProvider.Set(new ResourceTranslationInfo()
        {
            TranslationText = defaultValue,
            TranslationCultureID = culture.CultureID,
            TranslationStringID = resourceStringInfo.StringID,
        });
    }
});

We need to create an instance of <code>LocalizationCreator<T></code> and call it's <code>CreateLocalizations method</code>