Dicse

A straight-forward translation engine for ASP.NET MVC.

Dependencies

Newtonsoft.Json >= 5.0.8

Installation

Install the NuGet package:

PM> Install-Package Dicse

Creating a dictionary

Dicse currently supports two dictionary formats: JSON and XML. Each dictionary contains one language, and multiple contexts.

You'd use the context for translating the same word under different subjects. For instance, the word bit can be interpreted as the basic unit of information in computing or as a tiny piece of something. Thus, you'd use the global context for the default behaviour, and a different context for the specific meaning.

Also, contexts allow you to group translation keys by subject or by anything that suits you best.

The JSON dictionary

{
  "Language": "es-es",
  "Translations": {
    "global": {
      "Hello": "Hola",
      "Goodbye": "Adiós",
      "Hello {0}": "Hola {0}"
    },
    "family": {
      "Hello": "Hey, qué tal?",
      "Goodbye": "Hasta luego!"
    }
  }
}

The XML dictionary

<?xml version="1.0">
<translations language="es-es">
  <contexts>
    <context id="global">
      <entry key="Hello" translated="Hola"/>
      <entry key="Goodbye" translated="Adiós"/>
      <entry key="Hello {0}" translated="Hola {0}"/>
    </context>
    <context id="family">
      <entry key="Hello" translated="Hey, qué tal?"/>
      <entry key="Goodbye" translated="Hasta luego!"/>
    </context>
  </contexts>
</translations>

Configuring Dicse

In order for Dicse to work, the dictionaries must be loaded first.

A recommended way to do this is to create a TranslatorConfig class in the App_Start folder of your MVC project, containing the following:

public class TranslatorConfig
{
    public static void ConfigureTranslations(Translator t)
    {
        // Load a translation file.
        t.LoadFromFile("~/Translations/es-ar.json");
        
        // Set a default language.
        t.DestinationLanguage = "es-ar";
    }
}

Afterwards, you must call the ConfigureTranslations method in your Global.asax file:

public class MvcApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        // ... all other inits ...
        
        TranslatorConfig.ConfigureTranslations(JsonTranslator.Default);
        // or
        TranslatorConfig.ConfigureTranslations(XmlTranslator.Default);
    }
}

In the Application_Start event, you must define which translator engine to use (JSON or XML). You cannot mix between dictionary formats, you must pick one.

Localizing your text

To use Dicse in your views, simply use the Translate method in the Html helper:

@Html.Translate("Hello")

You can also translate with tokens:

@Html.Translate("Hello {0}", "John Doe")

If you need to reference a specifix context, prepend the context name along with a pipe (|) to the translation key:

@Html.Translate("family|Hello")

You must include @using Dicse.Json; or @using Dicse.Xml; at the top of your view so Razor can recognise the extension methods of HtmlHelper.

Optional: Register the Dicse namespace in your Razor Views web.config file

If you want to avoid having to add the @using Dicse.Json; or @using Dicse.Xml; on every view you wish to translate, you must register the Dicse namespace on the <pages> section of Views/web.config:

<system.web.webPages.razor>
  <host factoryType="System.Web.Mvc.MvcWebRazorHostFactory, System.Web.Mvc, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
  <pages pageBaseType="System.Web.Mvc.WebViewPage">
    <namespaces>
      <!-- 
      ...
      ...
      other namespaces
      ...
      ... -->
      <add namespace="Dicse.Json" /> <!-- or <add namespace="Dicse.Xml" /> -->
    </namespaces>
  </pages>
</system.web.webPages.razor>

Important: If you have your view file open while performing the forementioned changes to the Web.config file, close all view files and then reopen them, otherwise Razor won't recognise the Translate method.

License

Dicse is licensed under the MIT License.

Contribute

Feel free to fork this project, report issues and propose pull requests!