Installing FairlyLocal

Installing FairlyLocal is fairly straightforward. We built it so that it would simply drop into an existing project with the least amount of disruption.

Before following these instructions, you should download the library and tools.

Copying files

You'll need to copy some of the files from the source distribution into your project and into places that the project can find them.

• Put the GNU stuff someplace you can find it relative to your project. Usually, you'll have a folder near your projects that holds common 3rd-party dependencies. That's a good spot for these tools.
• Drop the /Localization directory straight into your project, either right at the root or into a /Helpers folder if you have one.

Modifying an existing project

If you're already using the Best-Practice technique of defining your own Page object that you use as the base for all your pages, this part should be simple. If not, you get to touch every file in the project, thus demonstrating why it's a Best Practice to not base anything directly off of System.Web.Page.

• Modify the base Page object for your site. Basically, this involves changing every WebForm that's currently inheriting from System.Web.Page to instead be based off of FairlyLocal.InternationalPage.

Hopefully, you won't need to do a giant search & replace to pull this off because you already have your own MyApplicationPage that you're using. Either base MyApplicationPage off of InternationalPage or simply tear the meat out of InternationalPage and paste it into MyApplicationPage.

• Add a post-build action to your debug build. The code below does 3 things:
• creates a text file containing the paths to all the .aspx, .ascx , .cs, and .master files in your project.
• generates a .pot file based on _() calls in those source files.
• merges the .pot file into the (possibly) existing .po file for English
• merges the .pot file into the (possibly) existing .po file for Spanish
dir $(ProjectDir)\*.aspx /S /B > projectfiles.txt dir $(ProjectDir)\*.ascx /S /B >> projectfiles.txt dir $(ProjectDir)\*.cs /S /B >> projectfiles.txt dir $(ProjectDir)\*.master /S /B >> projectfiles.txt rem Create a new .pot from source, place it in the English folder, and merge with the existing .po file in English mkdir $(ProjectDir)\locale\en\LC_MESSAGES if not exist $(ProjectDir)\locale\en\LC_MESSAGES mkdir $(ProjectDir)\locale\en\LC_MESSAGES if not exist $(ProjectDir)\locale\en\LC_MESSAGES\messages.po copy $(ProjectDir)\locale\en\LC_MESSAGES\newmessages.pot $(ProjectDir)\locale\en\LC_MESSAGES\messages.po $(ProjectDir)..\Gnu\xgettext.exe -k_ --from-code=UTF-8 -LC# --omit-header -o$(ProjectDir)\locale\en\LC_MESSAGES\newmessages.pot -fprojectfiles.txt $(ProjectDir)..\Gnu\msgmerge.exe --backup=none -U $(ProjectDir)\locale\en\LC_MESSAGES\messages.po $(ProjectDir)\locale\en\LC_MESSAGES\newmessages.pot rem Merge the newly created .pot file with the Spanish translations: if not exist $(ProjectDir)\locale\es\LC_MESSAGES mkdir $(ProjectDir)\locale\es\LC_MESSAGES if not exist $(ProjectDir)\locale\es\LC_MESSAGES\messages.po copy $(ProjectDir)\locale\en\LC_MESSAGES\newmessages.pot $(ProjectDir)\locale\es\LC_MESSAGES\messages.po $(ProjectDir)..\Gnu\msgmerge.exe --backup=none -U $(ProjectDir)\locale\es\LC_MESSAGES\messages.po $(ProjectDir)\locale\en\LC_MESSAGES\newmessages.pot Naturally, you'll need to fix up some paths so that this actually points to the folder where you dropped the gettext tools. You'll also need to modify it every time you add a new language to your project. Hopefully, doing so should be relatively straightforward.

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.

It's probably a good idea to keep the .po files under source control so that they'll deploy along with the rest of your site.

Known Issue:

The .po files that the build script generates won't be UTF8 by default. You'll need to open them in POEdit (or similar) and explicitly change the encoding the first time you edit them if you want your translated text to correctly show special characters. Sorry!

Note that you can still use UTF8 files with FairlyLocal (that's what it expects, actually). It's just the silly build script that's not generating new, empty .po files in UTF8. Fix it once when you start a new project and you'll be good to go from there on out.