Aurelia advanced I18N
Recently I had to implement i18n in order to support several languages and users all around the world. I used the official aurelia-18n library and had some difficulties make everything work in Safari (Cordova iOS App) and with Typescript. This post will cover and extend some steps that are already described in the README.md page of the Github repo.
I used the beta version of the library but shortly afterward Aurelia 1.0 was released and I updated to aurelia-i18n 1.0 version without any issues.
Using aurelia-i18n with Typescript
Like on the Github page suggested you have to execute
or some other backend service from this list of available backends and install typings
Since i18next-xhr-backend comes with a d.ts file you can just add
to your tsconfig.js and the gulp typescript task will find and use the i18next-xhr-backend.d.ts file. If you are up to date with your aurelia packages you shouldn´t get any "Duplicate identifier" error messages. If you have some issues with this you could change the filesGlob path to only match the specific file or follow the steps described under point 8.ii.
Translation with ValueConverter
I didn´t want to pass the currently selected locale to every view or make it global so I created a wrapper around the nf and df value converters. These wrapper value converters always requesting the current locale first so you don´t have to provide this value in every view or make it global.
This approach was fitting for me because I don´t need the options. You could also extend the custom value converter parameters with a options object. The custom date format value converter would look similar. Then you can use them like this
I had to implement a selectbox to let the user easily change the locale. I wanted to style the selectbox properly and enable the user to search for a specific locale. Thus I choose the Select2 plugin and orientated on this blog post from Dwayne.
Similar to the blog post I created a custom element language-switch but instead of using events I am using a bindable property because I wanted to get the whole selected object and not only the key.
Safari und Intl
aurelia-i18n uses i18next a widely known internationalization library which depends on the window.Intl API. Unfortunately, the browser support for this API is limited. Thus for supporting Safari and some mobile browsers you have to install the polyfill intl.js
and include it somewhere in your project and into your bundles
Aurelia-i18n will only take this polyfill if window.Intl is not available, therefore you don´t need to install extra typings for it.
But that fixed not all of my problems and it caused me some headache to figure out how to solve them. I discovered that you have to include a JSON file for every locale you are supporting in order to use numberformat and dateformat. So I created a file where I included all needed locales and imported this file in my project. Next to that, you could use this file for determining supported languages for the language-switch.
You can include the whole folder or use the complete.js for importing all locales but because all these files together have a size over 56MB I choose to add them manually. For more optimizations you could load intl.js and all the needed locale files only if window.intl is not available.
When using the TValueConverter or TBindingBehavior in the view of the custom element I was testing, the compiler was complaining about "No BindingBehavior named 't' was found!" What helped was to include t manually to the test. Given this custom element
and given this unit test, you can include the binding behavior with
Here is a complete example extending the custom element testing example from Aurelia HUB page
Hopefully, this will help someone using aurelia-i18n or when struggling with Safari support. Feel free to write me an Email or create a pull request if I missed something.
Found some typo, want to give feedback or discuss? Feel free to contact me :)