Hosted Login and the en (English) Locales

The ui_locales parameter enables you to display your Hosted Login screens in the language/locale of your choice. (Well, assuming that that all the required translations for that language/locale are in your flow.) For example, here’s the Hosted Login sign-in screen rendered in French:

And what if you’d rather have your screens displayed in Armenian or Tamil or Xhosa or any of the other languages/locales supported by Hosted Login? In each case, all you have to do is make sure you’ve created translations in the desired language for all the text elements used on each screen.

Note. Although Hosted Login supports scores of different languages, the product includes just one built-in language: US English (en-US). To use a different language, you’ll have to create the translations yourself.

However, there is one minor issue you should be aware of when it comes to Hosted Login's supported languages and locales: somewhat ironically, the English language locales don’t work the way you might expect them to. Let’s show you what we mean by that.

To better explain the issue, we’ve set up a simple test flow that includes the following locales and the following values for the sign-in screen header (the textSignInScreenHeading field):

Locale

Sign-in Screen Heading

en (English)

This is plain English.

en-US (US English)

Welcome to Gizmo!

fr (French)

This is plain French.

fr-CA (Canadian French)

This is Canadian.

As you know, if you don’t include the ui_locales parameter in your authorization request the sign-in screen (as well as all the other Hosted Login screens) is rendered using the default locale (en-US). In our test environment, we'll start with an authorization request that leaves out the ui_locales parameter:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=https://oidc-playground.akamai.com/redirect_uri
    &scope=openid 
    &code_challenge=H8o8kIzgmaCyePk0k6oDL951magkY3sp_OK1qDJpJoA
    &code_challenge_method=S256
    &prompt=login
    &response_type=code
    &state=BoMJQN05KV0vkjSyI58Wg9rr4XVbakBu8HvFBF24bjY

When we make the preceding authorization request, the resulting sign-in screen looks like this:

That’s the default screen (rendered in US English), and that’s the screen we should be seeing (remember, if you leave out the ui_locales parameter your screens are displayed in US English)

Now, suppose we set the ui-locales parameter to fr-CA. That gives us an authorization request similar to this:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=https://oidc-playground.akamai.com/redirect_uri
    &scope=openid 
    &code_challenge=LzstBKbuYIywSljaZxn-eAYBfdqHProXxuxnGn-JL_Y
    &code_challenge_method=S256
    &response_type=code
    &ui_locales=fr-CA
    &state=P7jnzoSHHg2Ws4tZt7DisDv9WLc-AFpTt7cJk5gI_P4

When we make the authorization request, our sign-in screen looks like the following:

Note. Yes, that’s not a fully-translated screen: for this test we didn’t bother translating everything on the screen (in fact, all we did was add a distinctive header). The important thing is that we asked for Canadian French, and, based on the header, that's exactly what we got.

So far so good. Now we’ll try the same thing with the fr locale: basic French. We set ui_locales to fr and, when we render the sign-in screen, we see this:

Again, exactly what we expected to see.

But now things get a little tricky. In our flow we also have a locale (en) for basic English, and we have a sign-in screen heading translation for this locale (This is plain English). In our authorization request, we set the ui_locales parameter to en:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize
    ?client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &redirect_uri=https://oidc-playground.akamai.com/redirect_uri
    &scope=openid 
    &code_challenge=LzstBKbuYIywSljaZxn-eAYBfdqHProXxuxnGn-JL_Y
    &code_challenge_method=S256
    &response_type=code
    &ui_locales=en
    &state=P7jnzoSHHg2Ws4tZt7DisDv9WLc-AFpTt7cJk5gI_P4

And when make our authorization request, here’s what we see:

That’s not the screen we expected to see; instead, that’s the screen that uses the en-US locale rather than the en locale. This is the screen we thought we were going to see, but didn’t:

And no, we didn’t make a mistake in our authorization request; in fact, a quick glance at the address bar confirms that we correctly set the ui_locales parameter to en:

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/v2/login
    ?__aic_csrf=OoKCxVnuzKlR7vY_
    &claims=%7B%22id_token%22%3A%7B%22organization%22%3Anull%7D%7D&client_id=64430515-01ea-4f5d-82e4-c36161af0093
    &code_challenge=A231aaQTccvPbFXNhNJV8QixS0WXjPBCLlcuRBXBBP0
    &code_challenge_method=S256
    &prompt=login
    &redirect_uri=https%3A%2F%2Foidc-playground.akamai.com%2Fredirect_uri
    &response_type=code
    &scope=openid
    &state=yly9vYh1rrLjilQ7G5NKyQZdZqqbpUKER9zgAkig0t0
    &ui_locales=en

As it turns out, the problem isn’t with the authorization request; instead, the problem is that Hosted Login doesn’t currently respect the en locale. If you set the ui_locales parameter to en, Hosted Login substitutes the en-US locale instead. For most organizations that probably won’t be an issue, but it is something to be aware of, just in case.