Use attributes to manage translations

[wichert]

The current way to do translations with aurelia-i18n looks like this:

<p>${ 'message' | t}</p>

You then need to run a tool like i18next-parser over your templates to produce a JSON file, enter the canonical text in there and then pass that on to translators. There are several things I personally do not like about this approach:

• It requires you to always change two files when adding or removing texts.
• Not seeing the canonical text in the templates makes it harder to reorganise/modify templates - I always need to look in two places to see how a text is used, or edit in two places if I change the semantics and position of a text.
• It requires having to define a unique keyword for every text. This is needless extra work, and can lead to the same text appearing in multiple locations while using a different identifier. In my experience using an identifier also leads to problems with existing translation software: many translators can not deal with files where the identifier for a text is not the text itself, and some will only show the identifier to the user. As a translator being asked to translate header_intro_welcome without any extra context is quite difficult.
• It uses a very non-standard magic naming to insert variables __variable__ instead of a more common syntax like ${variable} or just $variable
• It does not seem to allow nested elements in a translated context. For example translating something like <p>Hello <em>${name}</em></p>. It is not uncommon to have translations that are nested 2 (and sometimes even 3) levels deep.

An alternative approach to managing translations in a HTML context is to use attributes to mark elements as translatable. One way of doing this is the zope.i18n syntax. I made a quick gist which shows what this looks like. A few notes about this example:

• line 2 shows the the simplest example: it uses the text of the h1 element itself as identifier.
• line 3 shows the use of an element inside a translation. The span is marked with an i18n:name attribute which is used in place of the element in the text seen by translators, as you can see on line 26 of the POT file. This allows the translator to move the span around in the translation as needed.
• Sometimes you have the exact same text in multiple places but with slightly different semantics, requiring different translations in other languages. This can be handled by specyfing a context for a message. You can see an example of this line 4.
• line 8 shows how you can still specify an explicit identifier by providing a value for the i18n:translate attribute. An extraction tool will normally add the canonical text as a comment to the message, as you can see on line 35 of the POT file.

The zope.i18n approach works quite well. I won't argue that it is perfect, there is certainly some room for improvement:

• Having to add an i18n:translate attribute to every element can become a bit repetitive. Genshi experimented with an alternative syntax and implicitly making all text translatable. I'm not entirely convinced that approach is better, but it is certainly interesting.
• There is no support for plural handling in the syntax. This might be easy to add. Amazingly in 10 years of using zope.i18n syntax I haven't needed to do that, but it is certainly a desirable feature to have.

Obviel has an implementation of a zope.i18n-inspired syntax that is also interesting to look at.

[zewa666]

Haven't had yet time to take a closer look at it but at least for two of the points there are solutions already present:

1. Non-standard magic naming Honestly I don't know what a standard would be or who would define that. POT? Anyways i18n allows you easily to define your own prefix/suffix. Take a look at those tests: https://github.com/zewa666/aurelia-i18next/blob/master/test/unit/feature.placeholders.spec.js
2. Nested translations Those work as well, added a new unit test for it: https://github.com/zewa666/aurelia-i18next/blob/master/test/unit/i18n.spec.js#L80-L82

[Aaike]

And here is a gulp task that works to extract keys and default values from the sources files to generates translation .json files. gooy/aurelia-i18next-parser

[zewa666]

I'll leave this issue open while we test the heck out of it and to track any additional issues related to this. @wichert your help would be greatly appreciated

[wichert]

I’m fighting a few deadlines today, but I’ll definitely look at this ticket and your work again over the weekend!