FairlyLocal Overview

FairlyLocal is a simple Internationalization (i18n) library that lets you do gettext-style i18n in ASP.NET.

I18n is hopelessly broken in ASP.NET. Microsoft has crafted a method of localizing websites that is so ridiculously complex that nobody anywhere is actually smart enough to do it.

Here, I'm releasing some code that I hope will single-handedly fix i18n in ASP.NET. It's based on the way that everybody else does it. Let's pause a minute to let that sink in, since many of my fellow .NET devs might not have been aware of this fact: There's another way of doing i18n, and it's so simple and straightforward that every other web framework uses it in some form or another to do multi-language websites.

In Django, PHP, Java, Rails, and pretty much everything else out there, you simply call a function called gettext() to localize text. Usually, you alias that function to _(), so you're looking at like 5 keystrokes (including quotes) to mark a piece of text for internationalization. That's simple enough that even lazy developers like me can be convinced to do it.

Here's an example of how you'd mark a piece of text for translation in an .aspx file: <%= _("Buy more socks.") %>

Here's how you'd do it in a .cs (or .aspx.cs) file: linkHome.InnerHtml = _("Home Page");

That's it. That's all the code you need to write on a day-to-day basis to localize your site. Everything else is handled by the FairlyLocal library that you'll drop into your project, and by a few free tools that you can download from the nice folks at GNU.

How it works

Gettext() works by sifting through your source code and generating .PO files at compile time. .PO is a simple text file format for storing messages and their translations that's basic enough to be edited in notepad by non-tech-savvy translators, but is popular enough that there are several existing editors built just for it.

Once those .PO files are in place and translated, FairlyLocal will read them in and keep them cached in memory on your web server. Whenever a request for a piece of text comes through, the library will look it up in the appropriate language hash, handing back the translated version of the text if possible, or an untranslated version if not.

The nice thing about all this is that you don't need to specify keys for each piece of text. Gettext uses the entire English text string as its own key for lookups. What if that text changes? No worries. A lot of smart people have spent time dealing with fuzzy match algorithms to keep your translation files in synch in the face of minor changes. It's actually pretty cool.

FairlyLocal figures out which language to show based on the language preference settings in your users' browser. If you'd like, you can manually change the display language for a user, so you could, for example, include some little flag icons on your site that your users can click to select his language of choice.

Setting it up

First, you're going to want to download the library and tools. Put the GNU stuff someplace you can find it relative to your project, and drop the /fairlylocal directory straight into your project someplace.

Next, you'll need to modify the base Page object for your site. Either base all your pages off of InternationalPage.cs or simply tear the meat out that class and drop it into the object you're currently basing your pages off of.

Finally, you'll want to add a post-build step to your web project that will run xgettext and update your .po files whenever you build.

Assuming that everything is set up correctly, you can start marking text for translation. Next time you build the project, you'll notice a /locale/ folder appear containing your first messages for localization. Grab the one from, for example, /locale/es/LC_MESSAGES/ and hand it off to your brother who speaks Spanish. When he gives it back to you, drop it back into the project and suddenly your site will start rendering in Spanish for anybody who asks it to.

Cool!