Tutorial 2: The LocalizationHelper

Before using this tutorial, please look at:

• Introduction: Hello World
• Tutorial 1: Hello JsLink

What is the Localization Helper?

The localization Helper is the thing you get back when you call @Html.Local(). It replaces the HtmlHelper (@Html) and allows you to build tags which use both localized and non-localized values. It allows you to very easily localize attributes and has some very handy methods.

Keep it simple

Here's a short comparison of some vanilla localization to show that we don't make localization more complicated than already it is.

Standard .NET:

@Imports AppName.My.HomeIndexResources
<p>@Messages.LocalizedParagraph</p>
or
<p><%$ Resources:HomeIndexResources, LocalizedParagraph %></p>

LocalizationHelper (BLocal)

@local.Paragraph("localizedparagraph")
or
@local.Tag("p", "localizedparagraph")

Although Razor's HtmlHelper was a HUGE step in the good direction, I still wasn't quite happy about it. When I did a rewrite of it with the LocalizationHelper, I decided to make some additional changes. Here is a simple demonstration:

Standard .NET (more complex example)

        @using (Html.BeginForm("Index", "Home", FormMethod.Post, new {id = "form", title = @Messages.FormTitle, @class = "myform " + formActive ? "active" : "", data_name="Sam"})) {
            
        }

LocalizationHelper (more complex example)

        @using (local.BeginForm("Index", "Home", null, FormMethod.Post).Id("form").AttrKey("title", "formtitle").Class("myform").ClassIf(formActive, "active").Data("name", "Sam").Open()) {
            
        }

As you can see, both take up about the same space, but the second example is more fun to type, easier to read and less prone to error.

Parts and SubParts

As you might be aware, BLocal automatically resolves Parts and Locales depending on which providers you injected it with. Out of the box we provide the MvcLocaleProvider and MvcPartProvider, which get their respective data from the HttpRequest context and the RouteValueDictionary behind the scenes.

For the PartProvider in particular, this means it will automatically resolve the current localization context to Home.Index (assuming you're on /Home/Index), or whatever Controller/Action you are on. Of course you don't always want to be in there, let's say you have some common text that appears on different pages.

Approach 1: Assuming these values are only needed for pages from the Home controller, define them on the "Home" part (will need to be edited manually with the debugger, or via the Localization Manager app which can be downloaded for free from this github)

Approach 2: We break out of our current context to go to a second part. This can be done in two ways:

<!-- Tip: create a static class containing all your general parts and then use them here instead of new Part() -->
@using(local.BeginPart(new Part("General"))) {
    @local.Paragraph("companyslogan")
}
or
@{
    //usually found at the top of the page
    var localGeneral = @local.ForPart(new Part("General"));
}
@localGeneral.Paragraph("companyslogan")
or
@local.ForPart(new Part("General")).Paragraph("companyslogan")

The first one is good for blocks of code in the same part. The second one is good for using throughout your app. There is also a .ForSubPart() method which allows you to divide one (perhaps large) page into different segments easily, or to further structure your general parts. I guess you can see where this is going.