xaki - Xaki 1.0.0-beta-0091
Simplified multi-language POCO localization for .NET Core
PM> Install-Package Xaki -Version 1.0.0-beta-0091 -Source https://www.myget.org/F/xaki/api/v3/index.json
> nuget.exe install Xaki -Version 1.0.0-beta-0091 -Source https://www.myget.org/F/xaki/api/v3/index.json
> dotnet add package Xaki --version 1.0.0-beta-0091 --source https://www.myget.org/F/xaki/api/v3/index.json
source https://www.myget.org/F/xaki/api/v3/index.json
nuget Xaki ~> 1.0.0-beta-0091
Copy to clipboard
> choco install Xaki --version 1.0.0-beta-0091 --source https://www.myget.org/F/xaki/api/v2
Import-Module PowerShellGet
Register-PSRepository -Name "xaki" -SourceLocation "https://www.myget.org/F/xaki/api/v2"
Install-Module -Name "Xaki" -RequiredVersion "1.0.0-beta-0091" -Repository "xaki" -AllowPreRelease
Copy to clipboard
Xaki is a .NET library for adding multi-language support to POCO classes. It includes a lightweight service for persisting and retrieving data to and from databases using any ORM.
Xaki works well with all versions of Entity Framework and includes ASP.NET Core support for automatic localization to language codes provided by routes, querystrings, cookies, and HTTP headers.
Introduction
Setting up classes to be multi-language starts by implementing ILocalizable
and adding LocalizedAttribute
to multi-language properties:
public class Planet : ILocalizable
{
public int PlanetId { get; set; }
[Localized]
public string Name { get; set; }
}
Internally multi-language content is stored as serialized JSON:
planet.Name = "{'en':'Earth','ru':'Земля́','ja':'地球'}";
To localize a list, say pulled from a database with Entity Framework, you can use the provided IObjectLocalizer.Localize<T>()
method:
[HttpGet]
public async Task<IActionResult> Index()
{
var planets = await _context.Planets.ToListAsync();
planets = _localizer.Localize<Planet>(planets).ToList();
return View(planets);
}
Getting Started
ASP.NET Core
1. Add NuGet Packages
For ASP.NET Core projects you'll add the Xaki and Xaki.AspNetCore NuGet packages to your project. While these packages are beta you'll install from MyGet:
Package Manager
Install-Package Xaki.AspNetCore
.NET CLI
dotnet add package Xaki.AspNetCore
You may also want to add the NuGet feed above to your nuget.config file at the root of your solution:
2. Add Xaki to Startup
Xaki follows the usual pattern to add and configure services in an ASP.NET Core host, to add Xaki and request localization update Startup.cs
to include:
public void ConfigureServices(IServiceCollection services)
{
// ...
services.AddMvc().AddXaki(new XakiOptions
{
RequiredLanguages = new[] { "en", "zh", "ar", "es", "hi" },
OptionalLanguages = new[] { "pt", "ru", "ja", "de", "el" }
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
// ...
app.UseXaki(); // must precede UseMvc()
app.UseMvc();
}
For a sample ASP.NET Core app see https://github.com/mehalick/Xaki/tree/master/samples/Xaki.Sample.
3. Create Localized Entity
Any Entity Framework POCO can be localizable by implementing ILocalizable
with one or more properties decorated with LocalizedAttribute
:
public class Planet : ILocalizable
{
public int PlanetId { get; set; }
[Localized]
public string Name { get; set; }
}
4. Add Localization to Controllers
Similar to ASP.NET Core's IStringLocalizer
and IHtmlLocalizer
you can localize objects and collections with IObjectLocalizer
, simply add it to any controller:
[Route("planets")]
public class PlanetsController : Controller
{
private readonly DataContext _context;
private readonly IObjectLocalizer _localizer;
public PlanetsController(DataContext context, IObjectLocalizer localizer)
{
_context = context;
_localizer = localizer;
}
}
You can now fetch entities and send the localized versions to your views:
[HttpGet]
public async Task<IActionResult> Index()
{
var planets = await _context.Planets.ToListAsync();
planets = _localizer.Localize<Planet>(planets).ToList();
return View(planets);
}
How does IObjectLocalizer resolve the current language?
IObjectLocalizer
uses ASP.NET Core's RequestLocalizationMiddleware
to resolve the current language and culture using:
- Querystrings
- Cookies
- Accept-Language Header
For more information see https://andrewlock.net/adding-localisation-to-an-asp-net-core-application/.
If you'd like to customize how IObjectLocalizer
resolves languages you can create your own resolver by implementing Xaki.AspNetCore.LanguageResolvers.ILanguageResolver
.
5. Editing Localized Entities
The Xaki.AspNetCore library includes a tag helper and model binder to make edit views and actions extremely simple.
Tag Helper
To convert any input into a rich localization editor simply replace <input for="Name" />
with <input localized-for="Name" />
:
<form asp-action="Edit">
<input asp-for="PlanetId" type="hidden" />
<div class="form-group">
<label>Name</label>
<input localized-for="Name" />
</div>
<button type="submit" class="btn btn-dark">Submit</button>
</form>
You'll automatically get a rich localization editor:
The editor automatically lists the individual language textboxes in the order they are specified in Startup.cs
and client-side validation is included:
Model Binding
The Xaki.AspNetCore library includes LocalizableModelBinder
which is automatically registered via services.AddMvc().AddXaki()
.
This allows the localization tag helper to correctly model bind to ILocalized
entities and view models in your actions:
[HttpPost("{planetId:int}")]
public async Task<IActionResult> Edit(Planet planet)
{
_context.Entry(planet).State = EntityState.Modified;
await _context.SaveChangesAsync();
return RedirectToAction(nameof(Index));
}
Here your localized properties are automatically bound:
- .NETStandard 2.0: 2.0.0.0
OwnersAndy Mehalick |
AuthorsAndy Mehalick |
Project URLhttps://github.com/mehalick/Xaki |
LicenseMIT |
Info9 total downloads |
0 downloads for version 1.0.0-beta-0091 |
Download (11.06 KB) |
Found on the current feed only |
Package history
Version | Size | Last updated | Downloads | Mirrored? | |||
---|---|---|---|---|---|---|---|
1.0.0-beta-0091 | 11.06 KB | Sat, 02 Feb 2019 09:27:20 GMT | 0 | ||||
0.0.12-beta-0090 | 11.05 KB | Sat, 02 Feb 2019 08:01:07 GMT | 0 | ||||
0.0.12-beta-0089 | 11.07 KB | Fri, 01 Feb 2019 09:02:01 GMT | 0 | ||||
0.0.12-beta-0088 | 11.06 KB | Fri, 01 Feb 2019 08:51:59 GMT | 0 | ||||
0.0.12-beta-0086 | 11.05 KB | Fri, 01 Feb 2019 08:28:29 GMT | 0 | ||||
0.0.11-beta-0080 | 11.16 KB | Fri, 09 Nov 2018 15:15:42 GMT | 1 | ||||
0.0.10-beta-0079 | 11.17 KB | Fri, 09 Nov 2018 15:05:41 GMT | 0 | ||||
0.0.10-beta-0077 | 11.4 KB | Wed, 24 Oct 2018 05:36:32 GMT | 1 | ||||
0.0.9-beta-0075 | 11.28 KB | Wed, 24 Oct 2018 03:41:25 GMT | 1 | ||||
0.0.8-beta-0074 | 11.01 KB | Tue, 16 Oct 2018 13:10:47 GMT | 0 | ||||
0.0.8-beta-0072 | 11.01 KB | Sun, 14 Oct 2018 09:45:06 GMT | 0 | ||||
0.0.7-beta-0071 | 10.47 KB | Sun, 14 Oct 2018 07:01:48 GMT | 1 | ||||
0.0.7-beta-0070 | 10.47 KB | Sun, 14 Oct 2018 06:53:09 GMT | 0 | ||||
0.0.7-beta-0068 | 10.48 KB | Sun, 14 Oct 2018 06:38:54 GMT | 0 | ||||
0.0.7-beta-0067 | 10.48 KB | Sun, 14 Oct 2018 06:29:21 GMT | 1 | ||||
0.0.6-beta-0066 | 10.47 KB | Sun, 14 Oct 2018 06:07:53 GMT | 0 | ||||
0.0.6-beta-0064 | 8.06 KB | Sat, 13 Oct 2018 15:32:51 GMT | 1 | ||||
0.0.6-beta-0062 | 8.06 KB | Sat, 13 Oct 2018 14:07:13 GMT | 2 | ||||
0.0.6-beta-0061 | 8.06 KB | Sat, 13 Oct 2018 13:55:27 GMT | 1 | ||||
0.0.6-beta-0059 | 8.07 KB | Sat, 13 Oct 2018 13:31:21 GMT | 0 | ||||
0.0.5-beta-0058 | 8.08 KB | Sat, 13 Oct 2018 12:30:28 GMT | 0 | ||||
0.0.5-beta-0057 | 7.73 KB | Sat, 13 Oct 2018 12:25:10 GMT | 0 | ||||
0.0.5-beta-0056 | 7.72 KB | Thu, 04 Oct 2018 10:26:45 GMT | 0 | ||||
0.0.5-beta-0055 | 7.73 KB | Wed, 03 Oct 2018 03:15:21 GMT | 0 | ||||
0.0.5-beta-0053 | 7.49 KB | Sun, 23 Sep 2018 07:05:30 GMT | 0 | ||||
0.0.4-beta-0051 | 7.48 KB | Sun, 23 Sep 2018 06:55:33 GMT | 0 |