XperienceCommunity.Localization.Base
2.0.0
dotnet add package XperienceCommunity.Localization.Base --version 2.0.0
NuGet\Install-Package XperienceCommunity.Localization.Base -Version 2.0.0
<PackageReference Include="XperienceCommunity.Localization.Base" Version="2.0.0" />
paket add XperienceCommunity.Localization.Base --version 2.0.0
#r "nuget: XperienceCommunity.Localization.Base, 2.0.0"
// Install XperienceCommunity.Localization.Base as a Cake Addin #addin nuget:?package=XperienceCommunity.Localization.Base&version=2.0.0 // Install XperienceCommunity.Localization.Base as a Cake Tool #tool nuget:?package=XperienceCommunity.Localization.Base&version=2.0.0
XperienceCommunity.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
Xperience Version | Library Version |
---|---|
>= 30.0.0 | >= 2.0.0 |
>= 29.6.0 | >= 1.4.0 |
>= 29.2.0 | >= 1.2.0 |
>= 28.4.3 | 1.0.0 |
Dependencies
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
Add this library to the application services.
// Program.cs builder.Services.AddXperienceCommunityLocalization();
Open the Localization application added by this library in the Xperience's Administration.
Press Create to add a localization.
Fill out the key and the description of the localized content.
Add translations for the desired content languages.
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);
}
- 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.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Kentico.Xperience.Core (>= 30.0.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on XperienceCommunity.Localization.Base:
Package | Downloads |
---|---|
XperienceCommunity.Localization
Enables localization for Xperience by Kentico. |
|
XperienceCommunity.Baseline.Localization.Library.Xperience
The Baseline a set of Core Systems, Tools, and Structure to ensure a superior Kentico Website that's easy to migrate, for Kentico Xperience 13 and eventually Xperience by Kentico |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
2.0.0 | 70 | 12/20/2024 |