CODEWITHSUNDEEP
aureliai18next
LStarky
LStarky

Reputation: 2777

What is the preferred Aurelia i18n localization template usage?

I'm new to Aurelia but really enjoying it so far. However, the documentation is still lacking for some aspects, like the use of the i18n Plugin for localization.

I have language files set up (translation.json) and am inserting the language text tags into the HTML templates, but I see two different formats. I have gotten both to work successfully but I don't know the advantages and drawbacks of each so I'm hesitant to commit to updating all of my templates unless I know which is best and why.

locales/en/translation.json

{
  "hello": "Hello, World!",
  "lang_msg": "This message is in English."
}

locales/es/translation.json

{
  "hello": "¡Hola, Mundo!",
  "lang_msg": "Este mensaje está en español."
}

Template format 1:

<template>
  <h1>${ 'hello' | t }</h1>
  <h2>${ 'lang_msg' | t }</h2>
</template>

Template format 2:

<template>
  <h1><span t="hello"></span></h1>
  <h2><span t="lang_msg"></span></h2>
</template>

Should I use template format 1 or 2? Why?

Upvotes: 2

Views: 993

Answers (2)

zewa666
zewa666

Reputation: 2603

Fred summarized all of the three ways perfectly. So as an addendum to the original question ValueConverter | (VC) vs BindingBehavior & (BB) there is one small difference in performance. A BB essentially sets up additional listeners in order to support the automatic updating. As such it could make a difference in a very large set of bindings.

There are use cases where all you want to do is to translate once and changes never happen again. This one used to be pretty standard in the old days where you'd have the localized version as part of your URL and thus a switch to another lang would introduce a full page-reload. As such VCs are perfectly suited for these scenarios and also are a tick faster compared to the other two approaches.

As a bottom line, Aurelia and thus all of its plugins don't try to second-guess your business / use case. There are so much various, subtle differences that we can expose conventions, so you save time and dont have to write boilerplate, but you'll always find workarounds and at least one other option. That's why I18N has not one but three different ways to do what you want, so you have the freedom to chose what fits your story best.

Upvotes: 5

Fred Kleuver
Fred Kleuver

Reputation: 8037

It boils down to what feels most "natural" as an extension to your existing markup, what's least invasive / would be most maintainable on the long run. This depends on your application structure.

There are some differences in functionality which may or may not be important to you, but other than that it's mostly subjective.

Format 2 (html attributes)

This approach is more semantic and makes internationalization a first-class citizen in your markup. If you need more than simple single-variable translation then this will probably result in more readable/maintainable code than when you had to combine code from ViewModels and pass these variables to binding pipes.

From the docs:

Nested and combined translations:

<span t="$t(title) $t(subtitle)">Title subtitle</span>

<span t="nested_referencing">Nested text</span>

Parameratized attributes:

<span t="[html]paramstest" t-params.bind="params"></span>

For content-centric applications (like CMSes) or the outputs of those (like promotional websites) where you might use these things, this could be the preferred method.

Format 1 (TValueConverter)

Although subjective, I'd argue that ${ variable | t } is the more declarative / less intrusive approach. You're saying "I have this existing markup and I'm adding internationalization on top of that".

The TValueConverter approach will simply result in less code, which is an argument for maintainability.

The only drawback is that it does not update itself automatically when the locale changes, for instance.

Which can be overcome with the TBindingBehavior approach:

Format "3" (TBindingBehavior)

The usage is identical to that of TValueConverter, you only need to change | t to & t. This will automatically update when changes happen outside and you have the option of manually updating your bindings using the BindingSignaler

BindingBehaviors are by their nature more flexible (but also more complex to implement) than ValueConverters. I don't really see a reason to use | t over & t from a consumer perspective, as the amount of code to write is the same but the provided functionality is richer.

I hope this answers your question.

Upvotes: 6

Related Questions