Document GUI i18n method

[zanerock]

To keep it simple, we do i18n with the GUI snippets. For any given site, if you want to fully support a language, you potentially update every JS, CSS, and HTML file for that site.

In reality, this not as bad as it sounds. Ideally, many standard files use images. If you need different images, you would still need to provide alternate files, but the images should in general be more stable than text and often will not need to be replaced or may be updated at a higher level, to, for example, switch L-R or vertical-horizontal orientations.

The standard idea is to use some key for each bit of text and, ideally, to have a single GUI snippet that references a key. E.g., rather than:

<input type="button" value="foo">Foo</input>

You could do:

<input type="button" value="foo"><i18n:msg key="foo" />lt;/input>

You would then define translation files like 'button-labels.en' and 'button-labels.ru', etc. In theory that sounds good, but in practice, it's not worth it. You reduce the number of files a little, but end up adding "yet another layer" to the system, and because of the mitigating factors already mentioned, you don't end up saving as much as you think.

It's also limiting in two ways. First, only changing the text is not really enough for i18n. Consider the case of i18n for ASL speakers. You might want to add very detailed annotations, or change the structure entirely in order to better map to an entirely different sensory regime.

Second, we use the WUI templates for more than just i18n. They are also used for 'immersive styling'. Here again, the immersive style may veer from the standard and require the addition of structural elements or entirely different control types. By keeping things simple we can deal with all these cases relatively cleaning.

On the positive side, you could say that this approach is relatively simple and flexible, and these advantages more than make up for a bit of repeated code. If i18n is a big part of your app, and you need to support 100+ languages, then by all means, overlay a layer of i18n keys. Simple create WUI templates with controls like the one above and give a i18n extension, then add logic to generate dynamic templates based off the i18n WUI files and a separate repository of translation files keyed by the requested language.