By: Igor Afanasyev user 12 Feb 2020 at 5:05 p.m. CST

12 Responses
Igor Afanasyev gravatar
Hi everybody, Apart from **UI customization** (see https://support.gluu.org/authentication/7909/customization-of-various-page-ui-pages-in-gluu/ discussion) we need to **localize** the UI that comes from Gluu. I started asking around in https://github.com/GluuFederation/oxAuth/issues/1257 but since then realized we have a paid support, so moving the discussion there. I'll drop a bunch of questions here, if you don't mind: --- **1 - Two versions of the English resource file** Continuing the conversation from GH issue: I understand there was historically a default ("developer's English") version of the resource file (oxAuth.properties), and then a "proper English" version (oxAuth_en.properties). But this implies that users with unsupported locales will see a "developer English" version, if I understand correctly. So the current setup doesn't explain why oxAuth_en.properties couldn't be merged into oxAuth.properties, giving a single source of truth. The reason I ask is that for localization purposes, it makes sense to start off of the "proper English" version, but it seems these two were updated by hand and have diverged, i.e. it has some keys missing, or keys not present in the default .properties file, or translations with placeholders that are missing in the default .properties file. This needs to be consolidated into one .properties file for it to be localizable. --- **2 - List of localizable resources** Do you have a comprehensive list of resource files that need localization (i.e. expose UI strings)? This is what I've found so far (among the Gluu components that we plan to use): 1. Gluu oxAuth Server: * A: Server/src/main/resources/oxauth.properties * B: Server/src/main/resources/oxauth_en.properties 2. Gluu oxAuth RP: * RP/src/main/resources/messages_en.properties 3. Gluu Casa: * app/src/main/resources/labels/admin.properties * app/src/main/resources/labels/general.properties * app/src/main/resources/labels/user.properties 4. oxTrust: * static/src/main/resources/META-INF/resources/js/openid-en.js Anything that I'm missing? --- **3 - Non-externalized strings in XHTML** Looking at some XHTML templates, it seems there are bits of visible text that are not externalized into resource files (.properties), though some other XHTML templates do have text externalized. Is that something that you could take care of? Here are some examples with hardcoded strings: * oxAuth: RP/src/main/webapp/WEB-INF/incl/layout/template.xhtml * oxAuth: RP/src/main/webap/WEB-INF/pages.xml * oxAuth: Server/src/main/webapp/auth/thumbsignin/expired.xhtml And here's an example of a file with externalized strings: * Server/src/main/webapp/authz/authorize.xhtml (I'm talking about things like `#{msgs['authorize.doNotAllow']}`) --- **4 - Overriding resources** Since our plan is to override some of the Gluu UI, we will likely have a set of override strings that will be used in our UI only; however, it probably makes sense to keep them as additional resource bundle to make sure we can later update base resources from the upstream Gluu code without merge issues. Do you have any advice on how to approach this, or code examples / documentation? --- I'm open to do a sync up call if you need more information from me.

By Michael Schwartz Account Admin 12 Feb 2020 at 9:03 p.m. CST

Michael Schwartz gravatar
Jose, can you take a look at this?

By Jose Gonzalez staff 13 Feb 2020 at 7:44 a.m. CST

Jose Gonzalez gravatar
> 1 - Two versions of the English resource file Thanks for sharing your opinions. I agree there is room for improvement here > 2 - List of localizable resources *oxAuth* In chroot place your `oxauth_<SUFFIX>.properties` files in folder `/opt/gluu/jetty/oxauth/custom/i18n` Files in `i18n` have preference over those existing inside oxauth.war (WEB-INF/classes/*.properties) which in github are listed at `https://github.com/GluuFederation/oxAuth/tree/<BRANCH>/Server/src/main/resources`. Here `<BRANCH>` should match the version of your Gluu Server, eg. `version_4.0` No restart should be required when adding/editing entries in `i18n` *oxTrust* In chroot place your `oxtrust_<SUFFIX>.properties` files in folder `/opt/gluu/jetty/identity/custom/i18n` Files in `i18n` have preference over those existing inside identity.war (WEB-INF/classes/*.properties) which in github are listed at `https://github.com/GluuFederation/oxTrust/tree/<BRANCH>/server/src/main/resources`. Here `<BRANCH>` should match the version of your Gluu Server, eg. `version_4.0` No restart should be required when adding/editing entries in `i18n` There are also some JSF validation files there. I'll post details on this later *Casa* See https://gluu.org/docs/casa/administration/localization/ *oxAuth RP* This is an OIDC demo app mostly used by developers, do you need to translate it too? > 3 - Non-externalized strings in XHTML > oxAuth: RP/src/... See my comment above on oxAauth RP > oxAuth: Server/src/main/webapp/auth/thumbsignin... We don't necessarily provide localizable pages for all existing custom scripts (custom authentication mechanisms). From the authentication methods found at `https://github.com/GluuFederation/oxAuth/tree/<BRANCH>/Server/integrations` you have to choose those of interest to your organization and see if the xhtml files linked in python files have proper localization. The most common will be OK (eg. otp, passport, etc.) while others may have some hardcoded strings or even miss translations other than English. The idea behind custom pages/custom scripts is offering organizations support for alternative authentication methods to a certain extent but most of times they have to add/tweak code and UI elements to get the desired result. > 4 - Overriding resources I think the `i18n` strategy in use by oxAuth, oxTrust, and Casa answers your question.

By Jose Gonzalez staff 13 Feb 2020 at 10:20 a.m. CST

Jose Gonzalez gravatar
For the sake of clarity regarding oxTrust... oxTrust strings are in `oxtrust_<SUFFIX>.properties` files. There is also one resource bundle for JSF validator/converter strings which resides in `messages_<SUFFIX>.properties`. No other files are required for oxTrust localization

By Mohib Zico Account Admin 22 Feb 2020 at 2:39 a.m. CST

Mohib Zico gravatar
Hello Igor, Just touching base to know if you have any question or confusion on this so far or not.

By Igor Afanasyev user 26 Feb 2020 at 10:53 p.m. CST

Igor Afanasyev gravatar
Hi folks, sorry for the silence; I'm waiting for our engineers to define the scope of customizations we will be doing to the UI, and the list of components that we'll use, and then I will follow up with further questions, if any. Having said that, it feels like it would be good to have item #1 addressed by Gluu, regardless of the scope of our customizations.

By Mohib Zico Account Admin 26 Feb 2020 at 10:57 p.m. CST

Mohib Zico gravatar
Hello Igor, NP. Thanks for the update! >> Having said that, it feels like it would be good to have item #1 addressed by Gluu, regardless of the scope of our customizations. @Jose.Gonzalez: may be we can open a github issue on this?

By Jose Gonzalez staff 27 Feb 2020 at 8:26 a.m. CST

Jose Gonzalez gravatar
Hi, I think @Yuriy.Zabrovarnyy is a better fit here. Originally I thought that oxauth was picking the locale from the browser's language as most webapps do, and thus such "developer English" version would be displayed in case of an unsupported language. But it seems this is not true because the custom pages are using the locale passed in the OIDC authz request, and when not set, it defaults to `Locale.ENGLISH`. Actually Clyton asked about it internally : > Hi everyone! Another question on customization: > How to trigger the localization on oxauth pages? The only way I got this working was with the query parameter ui_locales on the endpoint /oxauth/restv1/authorize… > Is there a better way to achieve this? For example, automatically from the browser accepted languages.. and it was unanswered. I consider Yuriy may determine what the best approach to take is. This includes making no changes at all because Igor/ Clyton can do `<f:view transient="true">` instead of `<f:view transient="true" locale="#{language.localeCode}">` for pages to pick user's browser language. Personally I agree with not having 2 English versions. Such unique English should be used as fallback when necessary. We have English native speakers in the team to guarantee we have proper English translations before a release is issued.

By Mohib Zico Account Admin 02 Mar 2020 at 2:52 a.m. CST

Mohib Zico gravatar
Thanks Jose. Let me talk to @Yuriy.Zabrovarnyy and @Yuriy.Movchan please...

By Yuriy Movchan staff 04 Mar 2020 at 4:39 a.m. CST

Yuriy Movchan gravatar
Hi Igor, I agree with all points above except only one related to `oxauth.properties`. The base bundle name is `oxauth` as result JSF uses it as fallback i18n properties file for case like when message not defined in localization file or there is no localization file at all. I've open issues to review [oxauth](https://github.com/GluuFederation/oxAuth/issues/1281)/[oxtrust](https://github.com/GluuFederation/oxTrust/issues/1925) properties in CE 4.2. We need to remove deprecated mesages and make sure that all translation properties have all keys. There are few changes in 4.2 (dev version) which we implemented already: 1. oxAuth automatically select language based o browser preferences if there is no `ui_locales` in AuthZ request. You can see this here: https://jenkins-ldap.gluu.org 2. oxAuth uses list of supported locales from `uiLocalesSupported` property instead of hardcoded list in `faces-config.xml` 3. Now it's possible to use message properties like `oxauth_en_US.properties`, `oxauth_en_UK.properties`, etc.. 4. We prepared java extension to allow customize any message bundle. We will apply same changes to oxTrust as well. We can apply same updates to oxAuth-RP if needed. But this is development tool. Here is instruction how to customize JSF validation bundles, etc.. We made base version of java extension which allows to override java Message.properties. Here is the [code](https://github.com/GluuFederation/oxCore/tree/master/core-java-ext). You can download it from [here](https://ox.gluu.org/maven/org/gluu/oxcore-java-ext/4.2.0-SNAPSHOT/oxcore-java-ext-4.2.0-SNAPSHOT.jar). To enable it you need to do: 1. Put this library into `/opt/jre/jre/lib/ext`. 2. Check if inside `faces-config.xml` there is no `<message-bundle>` since we expects to use default `javax.faces.Messages.properties` bundle name. 3. Create new folder and put into `/opt/gluu/jetty/oxauth/custom/i18n/javax/faces` it Messages.* from `oxauth.war!/javax.faces-2.3.9.jar!/javax/faces/Messages.properties` 4. Restart oxauth service

By Igor Afanasyev user 04 Mar 2020 at 2:11 p.m. CST

Igor Afanasyev gravatar
Hi Yuri, I fully understand the use case where you have a base (generic English) bundle, but in certain cases want to have overrides with `oxauth_en_US.properties` and `oxauth_en_UK.properties`. However, I was talking about something different: what you have is two generic English bundles: `oxauth.properties` and `oxauth_en.properties`. Up until recently, `oxauth_en.properties` didin't simply override certain keys; it had keys that were not present in the base bundle, but I see that this is now fixed in most recent commits, and these two files are identical — this is basically what I asked for, so thanks for that! Just a suggestion: since you now have two identical files, you can safely remove `oxauth_en.properties` (or make it a symlink) so that `oxauth.properties` and `oxauth_en.properties` will never diverge again. :)

By Yuriy Movchan staff 11 Mar 2020 at 4:04 a.m. CDT

Yuriy Movchan gravatar
Hi Igor, Thank you for feedback. I opened issue in [git](https://github.com/GluuFederation/oxAuth/issues/1288) to remove this file in 4.2. I'm believe by 99.9% percent that we can do this without any issues. Can we close this support ticket? Regards, Yuriy

By Igor Afanasyev user 11 Mar 2020 at 1:36 p.m. CDT

Igor Afanasyev gravatar
Hi Yuriy, Yes, I believe we can close the ticket. Thanks! --Igor