Internationalising Open Banking using the i18n Framework

We might ask though, in the age of Google Translate, DeepL and browser translation plugins: “do we really need to manually translate our User Interfaces?”.

Many of our end users speak or at least code in English, so why bother?

• Whilst automatic translation is very useful on an ad hoc basis, it’s not perfect and it’s not always appropriate. For instance, automated translations might need to be corrected and external translation services might not be available – especially from internal banking networks.
• Many developers do speak English, but providing localised interfaces will hopefully give the software a wider audience.
• In some cases, we are returning translated data from RESTful API endpoints where browser plugins aren’t applicable.
• Finally, i18n is about more than just translation, it’s about date formats and display order and so on. It goes beyond language to adapt the software to different forms of data to match local customs.

So, having decided to translate, what exactly did we need to work on?

Our software stack has three main components that are generally installed together:

• The OBP API / Portal serves the RESTful API endpoints and provides user registration through a developer portal. This is a Scala / Java application and it uses the LiftWeb framework which has good i18n support.
• The API Explorer is a Graphical User Interface (GUI) used by developers to browse, discover and try out the endpoints. Our latest version is written in Node.js and Vue which has good i18n support.
• The API Manager is a GUI used by users who want to grant and revoke access, connect to backend sources and monitor API usage. This is a Python / Django application which also has good i18n support.

So we have three applications and three programming languages / web frameworks to internationalise.

Before we can add translations, we need to enable the software code base to display different text depending on the “locale” that has been selected. This “locale” is basically a two-part flag which tells the system what language and region the user is in or wants to “be” in. It can be set by a URL parameter and it’s also set in Cookies.

For example: https://apisandbox.openbankproject.com/?locale=en_GB sets the language to English and the region to Great Britain, whereas https://apisandbox.openbankproject.com/?locale=es_ES sets the language to Spanish and the region to Spain.

Setting a locale by clicking a link on the User Interface

Defining a list of the supported languages (JS)

The locale needs to be remembered by the system once a user has set it – and it needs to have a sensible default.

Each web framework has its own functions for use by developers who want to display translated text, but they are united by “PO files” — also known as portable files — which are generally used to store the original text or text codes (in English in our case) together with their translation.

So the first step in preparing the code base is to replace strings in the code base with calls to getText or equivalent functions. These getText functions mirror the original GNU Linux getText approach as documented here.

Scala translations codebase

Javascript codebase

Then, we need to provide the actual translations.

We have several flavours of text to translate.

User interface elements such as page titles, field names, menu items and buttons are essentially static content. They need to be translated but not on the fly. The translations will be baked into the OBP source code and will change infrequently.

Take the below example from the Intercam API Manager. The menu and navigation elements are static and translated to spanish.

API manager Spanish Navigation

Keep in mind that you have to translate less evident aspects of your platform too. For example, error messages:

Error message Invalid Credentials in Spanish

Certain descriptions and sections are designed to be changed by the client. These translations live in the OBP database or environment variables. They probably don’t change that frequently, but we consider them dynamic content because an end user can change them without changing code.

Last but not least, there is the API documentation. We need to be able to translate both static and dynamic API endpoints.

OBP API Scala translations

Remember that many languages use additional symbols on their characters. We’re working with Spanish so we have to watch out for accents. In this case, Java properties bundles use ISO 8859-1 encoding and require conversion to escaped formats. You can automate this process using tools such as native2ascii, which allows you to convert characters to a from their Unicode equivalents.

Look at the two screens below. The two files (EN) and (ES) contain the same words translated. The work we previously carried out on the codebase allows us to call these terms to be used in their equivalent locale.

API Explorer (Javascript) Translations (EN)

API Manager (Django / Python) EN

API Manager (Django / Python) ES

After laying the groundwork, it becomes easier to expand multi-language support by adding more locales.

Hopefully this article has given some insights into i18n and shown that it’s not too hard – but it’s also not trivial – especially when there is text coming from a variety of sources and some text can be user created.

Regarding i18n in open banking, when advising central banks and regulators internationally, we (TESOBE) like to encourage API standards that fit the local context and needs as much as possible – and local language documentation and educational content help to traverse language barriers and cultural differences. So, maybe we’ll see more multi-language Open Banking / Open Finance portals in the coming years!