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.
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.
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.
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.
acknowledgements
I'd like to thank CAPEM Solutions, Inc., for funding this development and agreeing that it bests serves the community as open source.