Localization in WSO2 Identity Server¶
WSO2 Identity Server enables a language picker on the following interfaces exposed to business users, allowing business users to select their preferred language.
- Interfaces related to the business user registration/sign-up flow, login flows (including MFA), and the account recovery flow.
- Interfaces of the self-care portal (My Account)
The default language on these interfaces is configured as explained in the language settings section.
Important
When user attributes configured on WSO2 Identity Server are displayed to users (during user sign-up and consent management flows), only the default user attributes get translated.
These interfaces are i18n-supported, which allows WSO2 Identity Server to update the text content from i18n resource files. This feature allows your business users to experience these use cases in their preferred language. The languages that WSO2 Identity Server currently supports are listed below.
Supported languages¶
Below are the languages currently available for the i18n-supported user interfaces of WSO2 Identity Server.
Language | Code |
---|---|
English |
en_US
|
French |
fr_FR
|
Spanish |
es_ES
|
Portuguese - Portugal |
pt_PT
|
Portuguese - Brazil |
pt_BR
|
German |
de_DE
|
Chinese |
zh-CN
|
Japanese |
ja-JP
|
Sinhalese |
si-LK
|
Language settings¶
The following methods can set the language used by WSO2 Identity Server interfaces exposed to business users.
Language switcher¶
The language switcher is available at the footer of the (i18n-supported) WSO2 Identity Server interfaces, which allows business users to select the preferred language for WSO2 Identity Server.
Note that WSO2 Identity Server will remember the language selected from this switcher, and it will be applied to all i18n-supported interfaces.
Browser-level settings¶
WSO2 Identity Server interfaces automatically adapt to the language preference set in the user's browser, as long as the language is supported by WSO2 Identity Server. However, the user can still change the language on the WSO2 Identity Server interfaces by using the language switcher.
Application-level settings¶
As an application developer, you can configure the application to send the ui_locales
parameter in the sign-in request or authorization request when the user signs in to the application.
Important
The ui_locale
parameter is only available for OIDC flows and not for SAML flows.
You can provide a list of strings, separated by a space, to define the locales. WSO2 Identity Server will search through the list until an WSO2 Identity Server-supported locale is found, and the first WSO2 Identity Server-supported locale in the list will be used as the default locale. If a supported locale is not found, WSO2 Identity Server will use the browser-level locale.
Consider the following examples:
- If the
ui_locales
is sent asfr_FR
, French is used as the default locale. - If the
ui_locales
is sent asfr_FR en_US
, French will be the default locale since it's the first WSO2 Identity Server-support locale in the list. - If the
ui_locales
is sent asit_IT en_US
, English (en_US) will be used as the default locale because the first given locale (it_IT
) is not supported.
The following examples demonstrate how to set the ui_locales
parameter in your application.
-
Example 1: Setting the default locale from the
signIn
request.You can send the
ui_locales
in the signIn request as a parameter.Note
Learn more about setting the signIn request using the WSO2 Identity Server SDKs.
The following sample illustrates the
signIn
request using the JS/React SDK.<SecureApp fallback={<div>Loading</div>} overrideSignIn={async () => { await signIn({ 'ui_locales': 'fr_FR en_US' }); }} > <AppContent/> </SecureApp>
-
Example 2: Setting the default locale from the authorization request.
If you are sending the locale in the authorization request directly, you can append the ui_locales
query parameter with the list of locales as shown below.
https://localhost:9443/oauth2/userinfo?scope={scope}&response_type=code&redirect_uri={redirect_uri}&client_id={client_id}&ui_locales={ locales list }
Privacy policy and Terms of conditions URLs
The privacy policy and terms of conditions URLs are specified in your branding configurations. The ui_locales={ locales list }
parameter is appended to these URLs, which allows you to show the translated content for the user from your end.
Configure localization for authentication endpoints¶
WSO2 Identity Server provides internationalization support for its web applications (such as the authentication endpoint located in the <IS_HOME>/repository/deployment/server/webapps/
directory). The following steps describe how you can configure this:
-
Navigate to
<IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/WEB-INF/classes/org/wso2/carbon/identity/application/authentication/endpoint/i18n/
-
Duplicate the
Resources.properties
file in the same location and rename it with the required locale suffix as follows:- For British English:
Resources_en_GB.properties
- For French (Standard):
Resources_fr.properties
Refer to Web browser language identification codes for more information on locale suffixes.
- For British English:
-
Update the values for each key as follows:
login=<Value in the required locale>
-
Save the file.
-
Navigate to
<IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/WEB-INF/classes/
and open theLanguageOptions.properties
file. -
Add information about the new language in the following format & save the file.
<language switcher name>=<language code>,<language name>`
-
Go to the browser settings and add the language you configured above.
-
Restart the server. To try out, do the following:
- Open up a browser.
- Type the My Account portal URL. (If you are running the server in your localhost, the URL is: https://localhost:9443/myaccount/). You will see the login screen having the contents in the configured language.
Configuring Localization for Recovery Endpoints¶
You can enable localization for accountrecoveryendpoint
by applying the same steps 1 through 8 in the previous section, for the following location:
<IS_HOME>/repository/deployment/server/webapps/accountrecoveryendpoint/WEB-INF/classes/org/wso2/carbon/identity/mgt/recovery/endpoint/i18n/
.
Update the LanguageOptions.properties file located at: <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/WEB-INF/classes/LanguageOptions.properties
to include the new language options.