Seamless Localization with Static Files on Apache 2.0.47+

The Benefits

I'm in the school of thought that thinks speakers of languages other than English shouldn't be given a second-rate website experience when the translations and technology for a first-rate experience all already exist. The setup I'm describing here will allow you to provide a localized experience that is as seamless as possible even if you only have part of the website translated. It was used successfully with English, French, and Japanese on an early version of the Mozilla Developer Center before they switched to a wiki.

There are numerous advantages to this scheme:

• It respects the visitor's Accept-Language headers.
• It allows overrides when the visitor wants to view a different language.
• It gracefully, automatically, and intelligently falls back when there are missing translations—without losing track of the language preference even in override mode.
• It does not use cookies or sessions or any of that kind of gunk.

All in all, it's better than the localization support in any content management system I've encountered. Which is a really sad state of affairs in the CMS world because it's so easy with static files. :)

What this scheme doesn't do:

• Help you keep your translations in sync
• Localize your templates (but see tips)
• Work on Apache 1.3. Gerv's Simple Language Content Negotiation With Override is probably the best you can do there.

The Method

Basic Language Negotiation with Fallbacks

You will need to set the following options:

AddDefaultCharset UTF-8
LanguagePriority en
ForceLanguagePriority Prefer Fallback
Options +MultiViews
DirectoryIndex index

Apache ships with common ones pre-set, but you may also need to set some AddLanguage directives.

When creating your files you will also need to observe the following rules:

• You must must use only relative links within the site, including in the navigation bars. No /foo, only ../../foo.
• You must name each file with a language code extension. That means using a .LANGCODE.html extension instead of a simple .html extension, where LANGCODE is en, fr, ja, etc.
• You must drop the file extensions in all links. That means linking to ../foo/bar instead of ../foo/bar.en.html.
• You must use UTF-8 for all files. (Although if your audience is heavily East Asian you might consider switching to UTF-16.)

This will direct the server to pick the most appropriate language available, based on the visitor's Accept-Language headers. It will fall back to English if no version in the visitor's preferred languages is found. (You can change the fallback language, or even specify multiple ones, by changing the value of the LanguagePriority directive listed above.)

The first three rules are not optional. Only break the fourth if you know what you're doing and have adjusted the server settings accordingly.

Language Overrides with Fallbacks

Sometimes a visitor will want to view articles in a language different from their browser preferences. Maybe they're borrowing a computer, or working on a translation. Apache has an environment variable that can capture this preference, and with the RewriteEngine you can set it based on a string in the request URI.

Create a top-level directory named after the language code for each language you plan to support and place in each a copy of the following .htaccess file, with LANGCODE changed to match the language code of that directory:

RewriteEngine On
RewriteRule   ^(.*)    ../$1 [E=prefer-language:LANGCODE]

For example, if I'm providing Japanese, I would create a top-level directory named ja and place in it the following .htaccess file:

RewriteEngine On
RewriteRule   ^(.*)    ../$1 [E=prefer-language:ja]

This will make a request to http://www.example.com/ja/foo/ internally fetch http://www.example.com/foo/index.ja.html overriding the visitor's Accept-Language header preferences. Unlike with a mechanically split site, if a page under the /ja/ virtual directory does not exist in Japanese, the server will fall back to language negotiation again. But—here's where the relative links requirement comes in—all the links are still going to the Japanese versions of other pages on the site. So when the user clicks a link on an English fallback page returned through the Japanese section, it's still going be requesting the Japanese version of the linked page.

So again, never link with the file extension and always use relative links. If you're targetting a specific language, use the ../../ja/foo/bar form, not the /foo/bar.ja.html form.

Tips for an International Website

• Understand that "language" and "nationality" are not the same thing. There are people who only speak Spanish in many countries of the world including the United States, and there are people who prefer reading Chinese, their first language, to English, their second, in the US and Norway as well as China. If you have separate content for different regions of the world, design the choice of region independently from the choice of language.
• Localizing templates is like localizing software: make every single human-readable string a variable and load in the appropriate set at the beginning. On d.m.o we required all files to set the lang attribute on <html> and then made the templates switch on that.
• If you are supporting Arabic or Hebrew localizations, make the templates provide an appropriate style sheet. (Indentation is on the right in right-to-left languages, text alignment is reversed, etc.)
• Ideally, make (only existing) translation choices available on each page.
• Always list language choices in their own language. You can put the language code, the English name, a flag, whatever you want in parentheses next to it, but if the visitor only reads Chinese and isn't a tech geek, "Chinese" and "zh" are not going to be recognizable whereas "中文" will be. If you are using images for some of the language names, make sure the alt text is the corresponding Unicode.