`static_gettext`: Localization for Static Documents

static_gettext is an internationalization framework for static, plaintext documents and templates. It’s geared towards straightforward translation of static websites, but can be easily used for any set of files you’d like to translate as a group.

static_gettext in a nutshell

Implemented as a thin wrapper around the GNU gettext project, static_gettext produces standard message files that any translator can easily work with. After translation, these can be used to generate localizations for your world-wide audience.

Workflow

Install the script by copying the latest stable version of static_gettext.py somewhere useful (I’d suggest ~/bin or /usr/local/bin):
```
curl http://github.com/mikewest/static_gettext/raw/v0.13/static_gettext.py > /usr/local/bin/static_gettext.py
```
Markup translatable strings in your documents by wrapping them in {% blocktrans %}...{% endblocktrans %} tags. This should feel familar if you’ve ever worked with Django’s i18n engine.

For example:
```
<h1>Hello, world!</h1>
```
Would be marked up as:
```
<h1>{% blocktrans %}Hello, world!{% endblocktrans %}</h1>
```
And so on…
Extract those strings into message files by pointing the static_gettext script to your source files, telling it which languages you’ll be localizing your documents into, and to a directory into which the message files ought be written:
```
static_gettext.py --make-messages --languages LANG_1,LANG_2,LANG_3,... --input=/path/to/source/files --locale=/path/to/locale/files
```
With that command, all files under /path/to/source/files will be read in, and a single directory per target language will be generated under /path/to/locale/files. You’ll end up with .po files for each:
```
/path/to/locale/files/en_US/LC_MESSAGES/messages.po
/path/to/locale/files/de_DE/LC_MESSAGES/messages.po
...
/path/to/locale/files/LANG_N/LC_MESSAGES/messages.po
```
These message files contain all translatable strings found in your source documents, and maps each to a target-language translation.
Translate the message files: In each message file, you’ll see a list of key/value pairs:
```
#: src/index.html:4
msgid "Hello, world!"
msgstr ""
```
Your job is straightforward: add the proper translation as the msgstr component of the pair:
```
#: src/index.html:4
msgid "Hello, world!"
msgstr "Hallo Welt!"
```
Easy!
Build localized versions of your documents by pointing the script at your source files, the target languages, the message file root, and a directory into which the localizations ought be written:
```
static_gettext.py --build --languages LANG_1,LANG_2,LANG_3,... --input=/path/to/source/files --locale=/path/to/locale/files --output=/path/to/output/files
```
A subdirectory of /path/to/output/files will be created for each target language, and each file inside /path/to/source/files will be copied over with translatable strings replaced with the target language version:
```
/path/to/output/files/en_US/index.html:

    <h1>Hello, world!</h1>

/path/to/output/files/de_DE/index.html:

    <h1>Hallo Welt!</h1>
```

The example project you’ll find in the GitHub repository shows the recommend project layout: everything in a single tree, with source files under ./src, message files under ./locale, and built localizations under ./build. Those serve as the defaults for the --input, --output, and --locale arguments.

Changelog

v0.13 (2010-10-28):
Adding rudimentary RTL support
- Added {{ LANGUAGE_DIRECTION }} tag that is replaced with either ltr or rtl according to a whitelist culled from Wikimedia. Thanks to Tom Bigelajzen for the push in the right direction.
- Converted isGettextAvailable to a static method.
v0.12 (2010-10-27):
Friendly error message when gettext utilities aren’t installed.
v0.11 (2010-10-03):
Adding {{ LANGUAGE_CODE }} tag to allow the current target language code to be embedded in the document. This is expecially useful for HTML documents. For example, <html lang="{{ LANGUAGE_CODE }}"> in the template will be rendered as <html lang="de-de"> in a German localization.

Magic!

Closes issue #3.
v0.10 (2010-09-26):
Changing workflow to remove the compliation step. There’s no good reason to expose that internal complexity to the user; she’s never going to compile the binary message file without also building the site.

Additionally, added the ability to change the list of file extensions that are parsed for translatable text. The default remains .html,.js,.css,.txt,.xml,.markdown but the user can now override that by providing an --extensions argument.
v0.9 (2010-09-12):
Initial public release.

Questions? Bugs?

If anything's unclear, file a bug via GitHub, or drop me an email

static_gettext: Localization for Static Documents

Workflow

Changelog

Questions? Bugs?

`static_gettext`: Localization for Static Documents