XperienceCommunity.Localization 2.0.0

XperienceCommunity.Localization

Localization

Description

This project enables creating and using localizations and translations in Xperience by Kentico project. Create translations in Xperience admin UI or programatically and use in your pages.

Screenshots

Library Version Matrix

Dependencies

• ASP.NET Core 8.0
• Xperience by Kentico

Package Installation

Add the package to your application using the .NET CLI

dotnet add package XperienceCommunity.Localization

You can optionally also install the XperienceCommunity.Localization.Base to any non-admin projects if you need.

Note on Version 2.0.0

In Version 2.0.0, we integrated our localization strings with the default Microsoft IStringLocalizer and IHtmlLocalizer. This works in tandem with any .resx you may also leverage.

Becuase of this, we removed the IKenticoHtmlLocalizer and IKenticoStringLocalizer as they are no longer needed. Please update any code needed and inject the standard IStringLocalizer and IHtmlLocalizer

This also means that you can use Localization keys in Attributes for any custom forms.

Quick Start

1. Add this library to the application services.

   // Program.cs
    builder.Services.AddXperienceCommunityLocalization();
   

2. Open the Localization application added by this library in the Xperience's Administration.

3. Press Create to add a localization.

4. Fill out the key and the description of the localized content.

5. Add translations for the desired content languages.

6. Display the results on your site with a ViewComponent.

Version 2.0.0 or above

    
    // ViewModelLocalizedWidgetViewComponent.cs
    private readonly IKenticoStringLocalizer localizer;

    public ViewModelLocalizedWidgetViewComponent(IStringLocalizer<OptionalResxClass> localizer)
        => this.localizer = localizer;

    public IViewComponentResult Invoke()
    {
        var model = new ViewModelLocalizedWidgetViewModel
        {
            Title = localizer["Title"],
            Content = localizer["Content"]
        };

        return View("~/Components/Widgets/ViewModelLocalizedWidget/_ViewModelLocalizedWidget.cshtml", model);
    }

Version 1.4.0 or below

    
    // ViewModelLocalizedWidgetViewComponent.cs
    private readonly IKenticoStringLocalizer localizer;

    public ViewModelLocalizedWidgetViewComponent(IKenticoStringLocalizer localizer)
        => this.localizer = localizer;

    public IViewComponentResult Invoke()
    {
        var model = new ViewModelLocalizedWidgetViewModel
        {
            Title = localizer["Title"],
            Content = localizer["Content"]
        };

        return View("~/Components/Widgets/ViewModelLocalizedWidget/_ViewModelLocalizedWidget.cshtml", model);
    }

5. Or display the results on your site with a Razor View 👍 Version 2.0.0 or above

@inject IStringLocalizer<OptionalResxClass> stringLocalizer
@inject IHtmlLocalizer<OptionalResxClass> htmlLocalizer

<div>
   <h1>@stringLocalizer["Title"]</h1>
   @htmlLocalizer["Content"]
</div>

Version 1.4.0 or below

@using XperienceCommunity.Localization

@inject IKenticoHtmlLocalizer localizer

<div>
    <h1>@localizer["Title"]</h1>
    <p>@localizer["Content"]</p>
</div>

Customization 2.0.0 or above

Version 2.0.0 integrates with the default IStringLocalizer and IHtmlLocalizer, you can optionally define a .resx file and class and use either the standard Resource File keys, or localizations created in the admin (admin takes priority).

If a key exists in the language of the current culture, the translation is returned. If a key exists in a fallback or default culture, but not the language currently requested, it will fall back to the fallback/default language.

If the key doesn't exist in either the .resx nor the Localization application, it will return the key you entered.

Additionally, you can add these helpful extensions to have a fallback values:

namespace Microsoft.Extensions.Localization
{
    public static class IStringLocalizerExtensions
    {
        /// <summary>
        /// Returns the GetString result, or the default value if not found or is empty
        /// </summary>
        /// <param name="stringLocalizer">The String Localizer</param>
        /// <param name="name">The Key Name</param>
        /// <param name="defaultValue">The Default Value</param>
        /// <returns>The value</returns>
        public static string GetStringOrDefault<T>(this IStringLocalizer<T> stringLocalizer, string name, string defaultValue)
        {
            var value = stringLocalizer.GetString(name);
            if(value == null || value.ResourceNotFound || string.IsNullOrWhiteSpace(value.Value) || value.Value.Equals(name))
            {
                return defaultValue;
            }
            return value.Value;
        }
    }
}

// Usage: @StringLocalizer.GetStringOrDefault("user.greeting", "Hello!");

using Microsoft.AspNetCore.Html;

namespace Microsoft.AspNetCore.Mvc.Localization
{
    public static class IHtmlLocalizerExtensions
    {
        /// <summary>
        /// Returns the GetString result, or the default value if not found or is empty
        /// </summary>
        /// <param name="stringLocalizer">The String Localizer</param>
        /// <param name="name">The Key Name</param>
        /// <param name="defaultValue">The Default Value</param>
        /// <returns>The value</returns>
        public static HtmlString GetHtmlStringOrDefault<T>(this IHtmlLocalizer<T> htmlLocalizer, string name, HtmlString defaultValue)
        {
            var value = htmlLocalizer.GetHtml(name);
            if(value == null || value.IsResourceNotFound || string.IsNullOrWhiteSpace(value.Value) || value.Value.Equals(name))
            {
                return defaultValue;
            }
            return new HtmlString(value.Value);
        }
    }
}

// Usage: @HtmlLocalizer.GetHtmlStringOrDefault("user.greeting", new HtmlString("<p>Hello!</p>"));

Customization 1.4.0 or below

Administration does not allow for storing empty string values as the translations. By default, if a specified key in a specified language does not exist the name of the key is returned

You can override this functionality by specifying your own implmentation of IKenticoHtmlLocalizer and IKenticoStringLocalizer. Default implementations are the KenticoHtmlLocalizer and the KenticoStringLocalizer.

This can be useful if you want to display a value in one language and display nothing in a different language. To achieve this, you can inherit the KenticoHtmlLocalizer or the KenticoStringLocalizer.

public class ExampleHtmlLocalizer : KenticoHtmlLocalizer
{
    public override string? GetStringByName(string name)
    {
        string culture = CultureInfo.CurrentCulture.ToString();

        // return empty string instead of null.
        return localizationService.GetValueByNameAndCulture(name, culture) ?? string.Empty;
    }
}

Similarly implement the IKenticoStringLocalizer, or use the default KenticoStringLocalizer

// In your Program.cs
// ... Other registrations
builder.Services.AddXperienceCommunityLocalization<ExampleHtmlLocalizer, KenticoStringLocalizer>();

Contributing

Instructions and technical details for contributing to this project can be found in Contributing Setup.

License

Distributed under the MIT License. See LICENSE.md for more information.

Support

This project has Limited support.