Think of the applications programming interface (API) for an application environment: an operating system, a markup language, a language’s standard library. What internationalisation (i18n) functionality would you expect to see in such an API? There are some obvious candidates: a text string substitution-from-resources capability like gettext(). A mechanism for formatting dates, numbers, and currencies in culturally appropriate ways. Data formats for text that can handle text in a variety of languages. Some way to to determine what cultural conventions and language the user prefers. There is clearly a whole list one could make.

Wouldn’t it be interesting, and useful, to have such a list?  Probably many organisations have made such lists in the past. Who has made such a list? Are they willing to share it with the internationalisation and localisation community? Is there value in developing a “good practices” statement with such a list?  And, most importantly, who would like to read such a list? How would it help them? In what way would such a list add value?

As I mentioned in my trip report from last month’s 37th Internationalization and Unicode Conference (IUC37), this idea came in a coffee-break conversation, and turned out to be one of the most interesting results of the whole event for me. One of my tutorial attendees had asked me, ”How good is the support for internationalisation in Joomla?” I made an ad hoc answer, but if I had had a list of good-practice i18n APIs, I could have evaluated Joomla’s i18n functionality against the list. Our industry has made many attempts at such APIs, from System/360 to .Net to HTML. Surely we could generalise from this experience. Of all the place to pursue this idea, the Unicode conference is one of the best. During successive coffee breaks, I followed leads to at least three people who had approximations of such lists in their organisations. My project now is to see if they are willing and able to share those lists.  Several people also identified the kind of person who would value such a list.

What would be the value of a good-practice list of i18n API functionality?

  • For anyone building or evaluating i18n support in an API, it would reduce the “unknown unknowns” — the things the evaluator doesn’t know, and is unaware they don’t know.
  • It would be a vehicle for i18n specialists in a software development organisation to communicate best practices to other parts of the organisation. Properly handled, it could be a tool for what the Japanese call gaiatsu, or outside pressure, to encourage the organisation to support i18n better.
  • It would make evaluating APIs and planning internationalisation projects easier and more comprehensive.

The conference discussions made it clear that there are many ways to get this list wrong. Some advised against making this list a checklist. It cannot be applied simple-mindedly to every API.  Products should only include that functionality which delivers value to their stakeholders in their context. It erode the list’s credibility for the list to pretend otherwise. It would be a shame for the list to be a tool for wasted work on API functionality solely to check off an item in the list, if the product and its customers don’t need it. I started off calling this a “best practices” list, but “best” is always relative to an audience and their needs, and I don’t think we know yet if this list’s audience shares an idea of what practices are “best”. I’ve stepped back a pace to the term “good practice”. It seems appropriate to consider it a catalogue of “design patterns”, rather than a prescription.

In my thinking, a good-practice list of i18n API functionality begs the production of a second good-practice list, of i18n features at the UI level of applications on a platform. That in turns begs the production of a suite of sample apps exercising the  i18n APIs and demonstrating the i18n UI features. I can imagine these simple apps might be good cookbook material for documenting an API.

I see this list as becoming a part of the internationalisation body of knowledge, freely usable. I don’t readily see how it could, or should, become a proprietary project.

Where am I going with this idea?  This post is a stake in the ground, describing the idea. I’m now looking into how much interest there might be in a project to draft this list. I am following up with contacts made at the IUC37. If those people who reported having such lists in their organisation are able to contribute them, I want to find that out.  I want to further identify the kinds of prospective consumers of this list. Such a project is only worth doing if it will add enough value to repay the effort it will take. I’d like to identify an organisational home for the project. While I could do it on my own, being part of an existing project would amplify my individual efforts, and make it easier for others to find out and to join in.

If you have something to contribute, be it a source list to draw from, or an identification of how such a list would add value, or a desire to help with the project, please contact me via this website. This might amount to nothing, or it might turn into a very interesting project for the industry.