The en-US locale is used in place of the en locale

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 supported languages? 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.


๐Ÿ“˜

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):

LocaleSign-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:


๐Ÿ“˜

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.