Multi Language Support

Exporting and Importing Guide Content

This section explains the process for exporting and importing Guided Learning guides for translation purposes. Translation of guides allows you to dynamically control which language of the guide will be displayed to the end user. Once the guides are exported you can translate the relevant text in the provided files and import them back to Guided Learning with the new language.

Export

Click Translation on the left panel of the OGL Console
Click Export (make sure the "properties" option is selected)

Guided Learning items will be saved as a ZIP file with all the exported content in the target folder (usually your "Download" folder).

Extract and save the information in the ZIP file to a folder of choice. If your operating systems does not support ZIP files you can use one of the following software providers: Winzip, Winrar, izip.

exporting

Your exported folder should include the following directories:

active - This folder contains all published/active revisions of your guides; it should match what you see in your production environment. The folder will contain a list of directories, one for each language. In each such language folder you will find a list of files named according to your guides’ api-names. The folder names ‘--’ denotes the native language you used to create your guides originally; this will be English in most cases.
testing - This folder contains all draft revisions of your guides; it should match what you see in your staging/test environment. The structure of this folder is identical to the active folder.
import - This folder has no real content. It is where you will need to place your translated guides before importing them back to Guided Learning. For more information about the import process please read the section below.
README.txt - this is the file you are reading now :)

Import

In order to import the translated guides back to Guided Learning you will need to populate the import folder with the translated content.

The import folder should include a folder for each language you support. The name of each folder signifies the language it contains and should follow this naming convention. For your convenience, during the export process we have generated in the import folder a folder for each language you currently have guides for in the Guided Learning servers. You can add more language folders if needed.

To import the translated content you will need to ZIP the contents of this language folder only and upload it using the “Import” button in the Translation section on the left panel of your OGL Console.

Click Translation on the left panel of your OGL Console
Choose the file to import; this is the zipped language folder in your import folder
Click Import (make sure Connected is checked)

importing

Foreign Language not Showing in Help Panel

So you've created your connected language folders and have content in them that you can see in the Console, you've updated the application.properties file and translated the guide property files, but still the Help Panel shows the same content that you see for the default language.

Did you update the Embedded Code?

If not, follow the steps listed below:

Instructions

JavaScript:
Add the following line to the Advanced Script:
iridize.lang = document.documentElement.lang == "en" ? "--" : document.documentElement.lang.toLowerCase();In JS 

Add the following line to the Config.js:
iridize.lang = document.documentElement.lang == 'en' ? '--' : document.documentElement.lang.toLowerCase();

Fusion Embed:
Add the following line to the Custom Script:
iridize.lang = document.documentElement.lang == "en" ? "--" : document.documentElement.lang.toLowerCase();

Native Fusion Integration for Language

If you have integrated via the native Fusion method, here is how to get additional languages working in your appId

Instructions

On the Configure Guided Learning page in Fusion

In the Customer Script field in the Advanced Settings section

Enter:

iridize.supported_langs = ['--', 'ja','es'];

iridize.lang = document.documentElement.lang == 'en' ? '--' : document.documentElement.lang;

iridize.lang = iridize.supported_langs.indexOf(iridize.lang) >= 0 ? iridize.lang : '--';

Replacing ja and es with whatever languages you want using the two letter abbreviation. Here is a link to the language abbreviation naming convention

Note: make sure you add your required languages in the 1st line of code, '-- ' always needs to be there.

Remove a Language from an appID

Sometimes an account will scale back on their guided learning implementation and no longer need a certain language that had been added to an appId. There is an easy way to do this now.

Go to the OGL Management Console for the appId you are working on. See below for example:
Change the url by replacing "#" with "oracle". See below for example.
(NOTE: Special permissions must be set up for your account on the back end to complete this task)
Scroll down to the Delete Language section:
Choose the language you wish to remove and select Delete.

Switching Language at Runtime

For the language change to take effect you should tell Guided Learning to refresh itself.

So after setting iridize.lang you will need to call the following API function:

Iridize('api.guide.refresh',{})

Add a condition so a guide only appears in a certain Fusion language

If a guide is pertinent to only one language, follow these steps so it is active only where desired:

Create your guide normally
Open Fusion in the language where you wish the message/guide/link to appear
Launch the guide from the OGL Editor and select 'Use Element Text' under ELEMENT SELECTION SETTINGS
In Activation settings, select 'Add' to add a step condition
Select an element in the language where the guide should appear.
Note: This must be specific to this language only. The example below is 'Mi equipo' (My team).
Open guide activation settings in your guide and add a 'page' condition. This example uses the HomePage.
Your guide will now only show in the required language, on the required page (in our example the Home Page) when the 'Mi equipo' element is visible

How to Request Machine Translation

Machine Translation may be requested up to 4 times per year using the following process. Review and validation is your responsibility.

Request desired language(s) by contacting your OGL Project Manager or by raising a support ticket. Refer to languages available below. Oracle will run Machine Translation, import the languages into the OGL console, and notify you of completion.
Validate the guides are functional in the foreign language and update both the guides and the translation(s) as necessary

Quality of translation estimated accuracy is 80%
Estimation of effort to validate and update: 15-30 minutes per guide per language

Languages available

Arabic
Dutch
French – Canada
French - France
German
Italian
Japanese
Korean
Polish
Portuguese - Brazil
Romanian
Spanish - Worldwide
Simplified Chinese
Traditional Chinese
Swedish
Russian

Hotspot Creation for Tracking Desktop Views and Mobile Views

Use Hotspots to gain insight into how your user population is accessing the application. Are users accessing the application via mobile devices or desktop devices?

Steps

Open Google Chrome
Enter the OGL Console URL
Sign in using your username and password
In a new tab, enter the Application URL and sign in to the application
Go to the OGL console, then select the New Content button.
Select Hotspot from the Guide Type dropdown
Enter the Application URL in the Location URL field
Enter Desktop Usage Hotspot in the Display Name in Widget. Replace XX with your initials.
Enter "This Hotspot monitors the Desktop usage" or similar in the Description field
Select Create Content.
Note: The OGL editor will open in a new tab.
Select any element on the page using right-click
Select the Step Settings icon
Select Advanced Settings
Select the Target Selector icon
Select the Edit Selector icon
Enter body in the selector field
Select the Check icon to save
Verify that your element selector is body, listed below/next to the Target Selector icon
Select Activation Settings
Verify that the Advance When setting is checked and User clicks element has been selected from the dropdown
Select Save and Close to save your work and close the editor. Your item will be available in the console.
Select the Activation icon
On the Guide Activation window, select Advanced Condition
Set the condition to Display when Page has URL matching /HomePage
Select the Autoload checkbox, then select Save Condition
Select the More icon, then select Clone
Rename the cloned Hotspot by clicking the Edit Guide Name icon, then rename the Hotspot to Mobile Usage Hotspot
Select the Save icon to save the name changes
Select the Settings icon for the Mobile Usage Hotspot
Update the Description to "This Hotspot monitors the Mobile usage" or similar
Select the Mobile setting checkbox, then select Save Settings
Publish both Hotspots

Moving Guides into an AppID with Existing Identical Guide API Names

Where a set of guides are migrated/copied/moved into an ApplicationID/Account containing guides with identical guide APINames, there will be duplicate APINames in the ApplicationID/Account. The guide(s) being migrated from the source AppID will NOT overwrite the existing guides (ApiName(s)) in the destination AppID.

In this case, only one of each ApiName should be active in the AppID. Duplicates should be inactive or deleted.

example of two with same id

How to Enable OGL on Career Sites

Open the Career Sites Configuration task in Setup and Maintenance
Select for the target Career Site, then select Edit
Select the Theme tab for the Career Site
Locate the Custom JavaScript section and select to expand menu
Check the Enable custom JavaScript checkbox
Paste the provided OGL JavaScript in the Display Editor Window field, then select Apply Changes.
IMPORTANT: Paste as Plain Text.
Verify that the OGL Help Widget is visible
Select Publish site

Content Security Policy (CSP) Error Correction

What is a CSP Error?

In simple terms, the OGL Help Widget will not load/display in the application due to a security policy.

Instead of blindly trusting everything that a server delivers, CSP defines the Content-Security-Policy HTTP header, which allows you to create an allowlist of trusted content sources and instructs the browser to only execute or render resources from those sources. The web's security model is rooted in the same-origin policy. For example, code from https://mybank.com should only have access to https://mybank.com's data, and https://evil.example.com should certainly never be allowed access. With this policy defined, the browser throws an error instead of loading scripts from outside sources (Source: Content Security Policy). This includes data from Oracle Guided Learning.

How to Troubleshoot

Right-click (Control-click on a Mac) on the application Homepage, then select Inspect from the menu.
Switch to the Console tab. Note the error in the Console relating to the Content Security Policy. It will read "Refused to load the script..." followed by the OGL URLs.

How to Correct a CSP Error

On the Fusion application Homepage, select the Settings and Actions icon () and then select Setup and Maintenance.

Alternatively, select the Navigator icon () → Others → Setup and Maintenance.
Select the Tasks icon () on the Setup and Maintenance screen to view the slide menu. Then select Search from the options in the slide menu.
In the search field, enter "Manage Administrator Profile Values" and then select the Search icon ().
From the search result, select Manage Administrator Profile Values.
A new window opens now, where you can manage Administrator Profile Values.
Enter ORACLE.ADF.VIEW.ALLOWED_ORIGINS in the Profile Option Code field and then select Search.

Note:
More information on this profile option can be found on Cross-Origin Resource Sharing.
Scroll down to view the Profile Value results displayed.
The field value may appear as "‘self’" or "‘self’ https://xyz.com" (with your organization-specific domain).
Depending on your data centre region, enter the Profile Value as provided below:
- NA Tenancy: 'self' https://guidedlearning.oracle.com
- EMEA Tenancy: 'self' https://guidedlearning.oracle.com https://guidedlearning-emea.oracle.com
- APAC Tenancy: ‘self’ https://guidedlearning.oracle.com https://guidedlearning-apac.oracle.com
Note:
- You may find the field value appears as ‘self’ <third party URL> or ‘self’ with your organization-specific URLs. Do NOT overwrite any URLs that are already defined, add the OGL URLs to the existing URLs.
- Use the whitespace separator (single space) between the URLs (i.e. 'self'<white_space><url_1><white_space><url_2><white_space><url_3>).
- You can find more details on this profile value in this Oracle article.
- This applies for Fusion version 21.04.0 or later.
Select Save and Close to save your changes and exit the Manage Administrator Profile Values task.
Log out of the application and log in again.
Go to the Homepage to verify that the OGL Help Widget is visible.

You have now successfully resolved the CSP error.
CSP Error in Non-Fusion Applications
If you experience a CSP error in your non-Fusion application, contact your IT support team to ensure that OGL-related servers and services are whitelisted.

Guide Activation Condition Troubleshooting

When Page Has Element / Visible Element

Depending on the version of JavaScript used to enable OGL on the application, activation conditions may not work as expected. This affects the 'when page has/has not element' and 'when page has/ has not visible element' conditions.

Review the OGL JavaScript and verify if it contains the following line:

window.addEventListener('load', function(){var e=document.createElement("script");var t=document.body;e.src=("https:"==document.location.protocol?"https:":"http:")+"//guidedlearning.oracle.com/player/latest/static/js/iridizeLoader.min.js";e.type="text/javascript";e.async=true;t.appendChild(e); });

Why does this happen?

The window.addEventListener line ensures that OGL loads after the application page has loaded. Therefore, it is not possible for OGL to determine whether or not the element is on the page.

Why should I do next?

DO NOT use the When Page Has Element/Visible Element conditions. Doing so will create inconsistent user experiences. Instead, set alternative conditions which suit the requirement.