How it usually works: build openradtool configuration and application logic, test, run, profit. Then, one day, check your server logs and see dropped transactions tied to un-satisfied Accept-Language HTTP headers. Dropped transactions = lost revenue. Time to translate!

So what are the tools fitting into our BCHS stack?

back-end translation

C source translation has a well-known toolchain, usually based on gettext and one of many translation managers (e.g., lokalize). But what do we do about jslabel strings in our ort(5) configuration files?

Since version 0.5.1, openradtool has had support for in-band multi-language representation of exported strings. Exported strings are jslabel declarations for enumeration and bitfield items that the ort-javascript(1) interface uses to format numerical values as human-readable text. It's handy to manage this in our configuration file because numerical values change and enumerations are augmented over time.

For example, we might want to format the enumeration value 2 of a nationality as Latvia when filling a user entry in the DOM tree. But if the HTML5 page registers itself as <html lang="lv">, it should instead show Latvija. We then use the jslabel.lv notation for these translations. The whole process is documented in Enumeration and Bitfield Labels.

Merging in-band translations for multi-language front-ends.

This is all good and well, but it has a big flaw: the translator (or translation utility) must have knowledge of the ort(5) file format. This is fine for one-off translations that may be merged by a developer, but doesn't scale.

So as of 0.5.2, a new tool, ort-xliff(1), allows for out-of-band translation, keeping your configuration nice and tidy. XLIFF is an industry-standard tool for maintaining translation dictionaries, and works with most open- and closed-source translation systems. It's documented as XLIFF Version 1.2.

Merging out-of-band XLIFF translations for multi-language front-ends.

This workflow allows you to manage your XLIFF files in any way you'd like—usually as dictated by your translator or translation service. The XLIFF files themselves are usually simply part of your sources and work with your BCHS system as directed by make(1). Usually, the XLIFF files are initially derived from the source configuration, translated, then merged back in. The post-merge configuration is then passed to ort-javascript(1).

front-end translation

What about the HTML5 front-end material? Given that they have the most text to translate, it stands to reason that we should spend the most time thinking about them.

There already exist several tools that are purpose-built for XML documents, amont them intltool. However, our toolchain is designed to work with XLIFF files. (The intltool suite works with PO files.) Enter sintl, which works specifically with HTML5 documents and XLIFF, specifically deriving from the XLIFF 1.2 Representation Guide for HTML. It completes the tool-chain for the HTML5 aspect.

Creating and merging out-of-band XLIFF translations.

By pairing these two strategies, your BCHS web application can have full out-of-band translation, leaving you to develop your templates and application logic, leaving the translations to the translators.


I'd like to thank CAPEM Solutions, Inc., for funding this development and agreeing that it bests serves the community as open source.