Obviel Template has extensive internationalization (i18n) support. It
lets you mark up those bits of the template that are translatable to
another language. This way you can easily construct user interfaces
can switch between different languages.

This document describes how to mark up translatable content in a
template. To read about how to actually integrate in a translation
workflow, and how to use i18n in JavaScript, read the i18n
manual.

Note: you can include the same variable multiple time in a message
id, but you must use the same formatter each time.

i18n works with {variable} notations. This:

<pdata-trans="">I saw {thing}.</p>

will imply the following message id:

I saw {thing}.

And this could be translated to Dutch like this:

Ik heb {thing} gezien.

The translator simply moves the variable to that part in the text
where it makes the most sense in that language.

Variables are also be re-orderable:

I saw {thing}. It was {color}.

could translate to the following Dutch:

{color} was {thing} dat ik gezien heb.

For HTML elements with simple textual content, and for any
translatable content that’s in HTML attributes, we’re done with the
explanations on how to mark up your template. But complexities occur
when we mark up an element that contains not only text, but also HTML.

data-each and data-if may not be used on elements contained in
an element with data-trans on it (when data-trans is used to
indicate the content of the element as opposed to attributes).

So, the following template is illegal and will not compile:

<divdata-trans=""><pdata-if="foo">Blah</p></div>

data-with and data-if may however be on the same element as
a data-trans attribute. In this case, they will be applied before
the data-trans attribute is applied. So, this is allowed:

<pdata-if="foo"data-trans="">Hello world</p>

If we’re just translating attribute content we’re fine as well:

<divtitle="A title"data-trans="title"><pdata-if="foo">Blah</p></div>

For the sake of simplicity of implementation, data-with is also
not allowed within a data-trans.

We introduce this rule because programmatic manipulation of
translatable text results in very hard-to-reason about situations that
are not really possible to resolve. If you need specific reasoning on
how to generate translatable text, we recommend you do this inside
JavaScript in the view definition.

data-tvar on an element implies that its content is translatable
as well; it is therefore very similar in behavior to
data-trans. This means a data-tvar may be nested within another
data-tvar element. For example:

<divdata-trans="">This is a <emdata-tvar="something">complicated <adata-tvar="thing"href="">scenario</a></em>.</div>

This results in the following pieces of text marked up for translation:

This is a {something}.
complicated {thing}
scenario

data-trans may not normally be used inside a data-trans, except when
it is used to mark up attributes:

In the above examples, the system will infer the message ids in the
translation files from the text in the template itself. Because in
some cases this can lead to ambiguous message ids, you may sometimes
want to be more explicit. You can name message ids by using a special
syntax in data-trans:

<pdata-trans=":hello_world">Hello world!</p>

In this case, the content of the p element will get the message id
hello_world, not Helloworld! as would have been the default.

When we go about using this, we run into a problem. What if count is
1? We’d see this:

<p>1 cows</p>

But this is wrong. We want to get this:

<p>1 cow</p>

English has two plural forms, one for the singular (1 cow) and one
for everything else, plural (5 cows).

We could change our template to use data-if to pick the right
plural form, but that will lead to a problem when we want to i18n our
template. Some languages have no plural forms, and others have more
than two, and will use different rules for selecting which plural form
to use based on count.

Instead we can mark up our template to indicate we want to use pluralization:

<pdata-trans=""data-plural="count">{count} cow||{count} cows</p>

We have introduce a data-plural directive that indicates that we
want to use the count variable to pick the correct plural form. By
default in English we have two plural forms, and we define them using
the || separator in a template. The singular form goes before
|| and the plural form goes after it.

When you run the template in the default locale, Obviel Template will
pick {count}cow or {count}cows for you automatically based
on count. When you run the template in another locale however what
translation string is picked can be determined from count in a
different way.

What if you want to translate an attribute? Let’s look at another example:

As you can see, you can use data-plural to indicate the
pluralization variable for the title attribute. The rules for
indicating an attribute or content work the same way as the rules for
data-trans, but the value after : is held to be the name of
the pluralization variable, not the message id.

data-tvar here deduced the variable name from the content of the
em element ({color}).

named views

View names are also not included in the message ids, so this:

<pdata-trans="">I saw <spandata-view="person|summary"></span>.</p>

will use the same message id as this:

<pdata-trans="">I saw <spandata-view="person"></span>.</p>

namely:

I saw {person}.

You can also always omit the data-tvar in case of a data-view
element:

<pdata-trans="">The great <spandata-view="foo"></span>.</p>

This will result in a message id like this:

The great {foo}.

Omitting data-tvar not allowed when an element contains something
else than just a single variable, such as text or sub-elements. This
for instance is illegal as it contains text (*) within the
em element:

This is now allowed however, because the em elements have a
(implied) data-tvar. Only directly embedded variables are
candidates for the implied data-plural rule. data-tvar does
not imply a pluralization variable as it is just a name to use
within message ids, and does not have to match any existing variable
at all. The pluralization system also does not look inside
data-tvar elements for pluralization variables.

When you use || within a data-trans or data-tvar element
or within an attribute, you automatically imply pluralization is in
use. data-plural is only necessary to indicate the pluralization
variable if it cannot be determined unambiguously automatically.

So this example:

<pdata-trans=""data-plural="count">{count} cow||{count} cows</p>

Can instead be written like this:

<pdata-trans="">{count} cow||{count} cows</p>

because count can be unambiguously determined to be the pluralization
variable, as it is the only one in use.