Localisation
You can handle different languages within your applications with Signicat. This page describes how localisation is handled during an authentication flow.
How it works
The Signicat eID Hub is localised to the languages shown in the table below. Note that English is the default (fallback) language.
Languages are formatted as lowercase two-letter codes in ISO 639-1. For example, en or no.
Order of priority
The language displayed on the graphical user interface (GUI) during an authentication flow depends on competing factors. The logic that determines what language is ultimately displayed to your end-users follows this order of priority:
- High: The authorisation request (authentication URL) your application sends.
- Medium: User browser settings (
Accept-Languageheader). - Low: eID method language support.
This relationship can also be represented by this formula:
ui_locales / language (request) > Accept-Language (browser) > en (fallback)
Note that English is always the fallback language.
Authentication language
When you start an authentication session and specify the language as a query parameter (for example, with ui_locales in OIDC), the following happens:
- The service tries to show content in the language defined in your request.
- If the language is not supported, then the service tries the language in the user browser settings.
- If language in the user browser settings is also not supported, then localisation defaults to English.
However, note that this may vary depending on the step in an authentication flow, as explained in the section below.
Authentication steps
An authentication session involves routing end-users through multiple screens and domains, which may affect localisation. A typical user journey involves the following steps:
- The user wants to authenticate in your application/website. Here, you manage localisation on your side.
- Optional. You direct the user to the eID selection screen where users can choose the eID method to authenticate with. Since this is part of the Signicat eID Hub, you can control the language with query parameters in the authentication URL.
Optional
Note that you may skip this step if you route the user directly to the eID portal with IdP scoping, or when you only support one eID.
- The user is routed to the eID authentication portal. Localisation depends on the languages supported by the eID method.
- The user is redirected back to your application/website. Similarly to step 1, you manage localisation on your side.
You can learn more about how this works for different scenarios in the Examples section.
We recommend that you let the end-users control the localisation settings, either automatically through their browser settings or by choosing supported languages in a dropdown list (if available). You should override the language only in specific cases.
How to edit the UI language
When you want to overwrite the default language for the GUI, each authentication protocol requires that you adhere to the appropriate syntax. Below, you can find examples for each authentication protocol:
- OpenID Connect
- SAML 2.0
- Authentication REST API
To change the language of the GUI, you need to define the query string parameter ui_locales in your OIDC authorization request. For example, you can set the language to Greek (ui_locales=el) by passing the following in your request:
https://<SIGNICAT_ACCOUNT_DOMAIN>/auth/open/connect/authorize?
&client_id=OIDC_CLIENT_ID
&response_type=GRANT_TYPE_CODE
&redirect_uri=REDIRECT_URI
&ui_locales=el
&scope=OIDC_SCOPES
Examples
The following examples show how localisation works for different authentication scenarios.
Supported language
Below, you find examples of how authentication flows look like when both the eID Hub and the eID method support the language configuration that you or your users require.
Scenario 1: Default
Imagine an authentication session where your application does not specify the language settings.
- End-user browser language settings: Norwegian
- Authentication URL language: Not specified
- eID method: Email OTP *
*Note that Email OTP supports Norwegian.
This will result in the following localisation in the authentication flow:
- eID selection page: Norwegian
- Email OTP page: Norwegian
In this scenario, the user browser settings determine the language for authentication because your request did not specify the language and Norwegian is supported by both the Signicat eID Hub and Email OTP.
During authentication, your end-users will see with the following screens:
Scenario 2: Specify language
Imagine an authentication session where your application specifies the language settings.
- End-user browser language settings: English
- Authentication URL language: Norwegian (
ui_locales=no) - Authentication method: Email OTP *
*Note that Email OTP supports Norwegian.
This will result in the following localisation in the authentication flow:
- eID selection page: Norwegian
- Email OTP page: Norwegian
In this scenario, the language parameter you passed in your request determine the language for authentication. This is possible because Norwegian is supported by both the Signicat eID Hub and Email OTP.
During authentication, your end-users will see the following screens:
Unsupported language
When you initiate an authentication session with a language that is supported by the Signicat eID but not supported by the eID method, the language might change during authentication to adjust to the eID method requirements.
- End-user browser language settings: French
- Authentication URL language: French (
ui_locales=fr) - Authentication method: Norwegian BankID *
*Note that Norwegian BankID only supports Norwegian and English.
This will result in the following localisation in the authentication flow:
- eID selection page: French
- Norwegian BankID: Norwegian
During authentication, your end-users will see the following screens:
When the user browser setting language is not supported by the Signicat eID Hub and you do not specify the language in the authorisation request, then localisation defaults to English.