https://github.com/joelalejandro/dicse

A straight-forward translation engine for ASP.NET MVC.
https://github.com/joelalejandro/dicse

Last synced: 5 months ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/joelalejandro/dicse
• Owner: joelalejandro
• License: mit
• Created: 2013-11-25T17:24:48.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2013-12-20T23:59:14.000Z (over 11 years ago)
• Last Synced: 2024-12-10T15:36:12.288Z (5 months ago)
• Language: C#
• Size: 136 KB
• Stars: 4
• Watchers: 1
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
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 `` 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!