Internationalization

Dates, times, numbers and currencies look differently in different parts of the world.

The same number may look like 1,250.50 in the US and like 1.250,50 in Germany.

If you want Doxey to work with numbers e.g. to sum up both numbers you may get into trouble if you do not specify the locale (=the language and country) that has been used to format the numbers in the first place.

Doxey helps you to deal with the these challenges, but it is important that you understand the basic concepts, so read this guide carefully.

Default settings

You can pass the default locale, timezone and currency when invoking the /merge API method.

If you do not specify the locale, timezone and currency in your API call, Doxey will use en_US, GMT and USD as defaults.

Input locale

The input locale will be used when Doxey tries to make sense from given numbers, dates or currencies.

Let’s say you have a variable called betrag with the value 1.250,50. It is a number, but it is formatted in the “German way”.

First of all make sure that you know how the raw data looks like by using the debugger or by printing the value to the console without any formatting:

${betrag}

You will get the unformatted value:

1.250,50

If your default input locale is set to English and you print the variable to the console using the number renderer ...

${betrag;number}

… you may get an unexpected result

1.25

Why is that?

As Doxey tries to understand the given value 1.250,50 using English formatting rules, it will take the first dot as the decimal delimiter and ignores everything after the comma.

The converted number is 1.25 and that’s what gets printed to the console.

If you set the default input locale to German Doxey will understand the number correctly and you will see a different result:

1,250.5

But what if you have some variables containing numbers in German and others in English format?

If you switch back your default input locale to English, you can still set the input locale on each merge tag. It will then not use the default input locale, but the specified input locale instead:

${betrag;number(il=de)}

Gives to correct number, even though the default input locale is set to English:

1,250.5

The same logic applies to given dates and currencies.

Playground

Rendering "betrag" as number with default input locale (en):
${betrag;number}
Set input local to German to parse "betrag"
${betrag;number(il=de)}
{
  "betrag" : "1.250,50"
}

   

Output locale

Let’s say you want to print the current date and time. If you just log

${now}

to the console, you will get an output like this:

Thu Sep 20 08:48:13 UTC 2018

This is just printing the raw date and time and does not look not very nice.

Let’s use the datetime renderer to improve the formatting.

${now;datetime(op=full)}

to the console, you will get an output like this if your default output locale is set to English:

Thursday, September 20, 2018 11:11:07 AM UTC

If you set your default output locale to German, you will get a different result:

Donnerstag, 20. September 2018 11:11 Uhr UTC

Playground

Change the output locale and output pattern to modify the emitted date.

Dates and times look differently in different languages
${date;datetime(op=full;ol=fr)}
${date;datetime(op=full;ol=it)}

Formatted dates can even vary in different countries speaking the same language
${date;date(op=full;ol=de;oc=AT)}
${date;date(op=full;ol=de;oc=DE)}
{
  "date" : "2018-01-12T15:00:00.000Z"
}

   

Time zone

You have learned how to print dates and times using the formatting rules of different locales.

By default they will be printed in the specified default timezone, which in our example has been set to UTC.

If you set the default timezone to Pacific Standard Time instead, when printing the current date and time...

${now;datetime(op=full)}

...you will get a different output with the correct time accordingly

Thursday, September 20, 2018 4:20:40 AM PDT

You can specify the output time zone in your merge tag to override the default settings and to print the same correctly for different time zones and languages like this:

${now;datetime(op=full;ol=de;otz=Europe/Berlin)}
${now;datetime(op=full;ol=pt;oc=BR;otz=Brazil/East)}

You will get the correct dates and times reflecting the formatting rules of the specified locale and time zone:

Donnerstag, 20. September 2018 13:25 Uhr MESZ
Quinta-feira, 20 de Setembro de 2018 08h25min41s BRT

Playground

Feel free to adjust the various parameters of the datetime renderer to get the desired result

Same time, different timezones
${date;datetime(op=full;ol=en;otz=Europe/Berlin)}
${date;datetime(op=full;ol=en;otz=Brazil/East)}
{
  "date" : "2018-04-12T15:00:00.000Z"
}

   

Currency

When formatting numbers with the currency renderer, the configured default currency will be used.

Let’s say you have a variable called amount with the value 1,250.50 and your default output locale is set to English (US) and the currency is set to EUR (Euro), printing this variable using the currency renderer…

${amount;currency}

...will generate output reflecting the configured default currency and output locale:

EUR12,505.00

Switching the default output locale to Italian will generate a different output:

€ 12.505,00

${amount;currency(ol=it)}
${amount;currency(op=USD;ol=en;oc=US}

Did you know that formatting currencies in Euro looks like this in the UK
${amount;currency(op=EUR;ol=en;oc=GB}
while it looks like that
${amount;currency(op=EUR;ol=en;oc=US}
in the US?

In Germany it looks like this
${amount;currency(op=EUR;ol=de;oc=DE}
while it looks like this
${amount;currency(op=EUR;ol=de;oc=CH}
in Switzerland
{
  "amount" : "1,250.50"
}

   

Learn more

The following guides will cover the aspects of the templating language.

Questions and Feedback

If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.

If you are not yet member of the Doxey community, please join now to get updates from our end or to provide feedback, bug reports and discuss with other users.

Last Updated: 03.01.20