Oracle by Example brandingCreate a Multi-language Application in Oracle Visual Builder: Create a Language Switcher

section 0Before You Begin

This 15-minute tutorial shows you how to create a language switcher in a web application with translation bundles for multiple languages.


You can create Oracle Visual Builder applications that readers of multiple languages can use. You can translate the strings in your user interface into other languages and upload them to your application. You can also create a language switcher component to allow users to change from one language to another.

The strings in a translated application are stored in translation bundles, which are JSON files that contain keys and values.

You should be familiar with the basics of creating an application, adding components and pages, and creating action chains.

In this tutorial sequence, the language you use is French.

What Do You Need?

section 1Specify Code for a Language Switcher

In this section, you'll set a locale property in an application JSON file to a value to be retrieved by a JavaScript function.

  1. If you completed the previous tutorial, Create a Multi-language Application in Oracle Visual Builder: Translate Application Strings, go to step 2.

    Otherwise, click this link and download If necessary, log in to Oracle Visual Builder. On the Visual Applications page, click Import and select Application from file. In the Import Application from File dialog box, click the box and select the downloaded zip file, and click Import. Then click TranslationApplicationPart2 to open it.

  2. In the Navigator, click the Source View Source View icon tab and expand the transwebapp node.
  3. Click app-flow.json to open it in the JSON tab.
  4. Insert a comma after "security":{} almost at the end of the file, and then, after the security definition, add the localization definition (in bold here) with a function to set the locale property value.
      "userConfig": {
        "type": "vb/DefaultSecurityProvider",
        "configuration": {},
        "embedding": "deny"
      "security": {},
      "localization": {
        "locale": "{{ window.localStorage.getItem('translationApplication.locale') || navigator.language }}"

    This code sets the value of the locale property to a locale value it retrieves from a language switcher, or to the browser locale if there is no locale value.

  5. Expand the flows, main, and pages nodes under transwebapp.
  6. Click main-start-page.js to open it in the Functions pane.

    You'll put the language switcher on the main-start page, so that's where you'll define the JavaScript function.

  7. Between the var PageModule definition and the return PageModule statement, define the PageModule.prototype.setAppLanguage function, which sets the locale if the selectedLocale input parameter is set. The text to be added is shown in bold.
      var PageModule = function PageModule() {};
      PageModule.prototype.setAppLanguage = function(selectedLocale){
        if (selectedLocale)  {
      return PageModule;

    The setAppLanguage function sets the language switcher locale value to the value retrieved from the function input parameter, selectedLocale. The next task provides a way to set that input parameter.

section 2Create Buttons for the Language Switcher

For this simple application, you'll use a pair of buttons to select the language. A more complex application could use a Select (Single) or other component.

  1. Click the Page Designer tab for the main-start page.
  2. On the main-start page, drag a Button from the Common components to the grid between the heading and the Create button.
    Description of vbcsta_sec2_s2.png follows
    Description of the illustration vbcsta_sec2_s2.png
  3. In the Button's Properties pane, enter English in the Text field.
  4. Slide the right button handle to the left so that the button takes up only one column of the grid.
    Description of vbcsta_sec2_s4.png follows
    Description of the illustration vbcsta_sec2_s4.png
  5. Drag another Button component to the right of the first button and enter French in the Text field.
  6. Select each button, mouse over the area opposite the Text label, select the Make String Translatable Make String Translatable icon icon, and click Save in the dialog box to make the text translatable.
  7. Click the Web Applications Web Applications icon tab in the Navigator. Under Resources/strings/app/nls, copy the added key strings from app-strings.json under root into app-strings.json under fr-FR. Make sure to copy the comma after the Save string, too. The code to be copied looks something like the text in bold here:
        "button__text_a1fe": "Save",
        "@button__text_a1fe": {
            "description": ""
        "button__text_6dd1": "English",
        "@button__text_6dd1": {
            "description": ""
        "button__text_4334": "French",
        "@button__text_4334": {
            "description": ""

    We could have returned to the application settings, downloaded the new strings, translated them, and uploaded them again, but this would take too long for only two strings. However, this way you have to make sure to use the correct JSON syntax.

  8. In the app-strings.json file under fr-FR, change the text as follows:
    English French
    English Anglais
    French Français

section 3Define an Action Chain for the Buttons

In this section, you'll define an action chain that you'll use for both buttons, by using an input parameter to set a different locale value for each action chain.

  1. Return to the main-start page, select the English button, and then click the Events tab.
  2. Click the + New Event button and select Quick Start: 'ojAction'.
  3. In the action chain's properties, click the Add link next to Input Parameters.
    Description of vbcsta_sec3_s3.png follows
    Description of the illustration vbcsta_sec3_s3.png
  4. In the dialog box, enter locale in the Id field, select the Required check box, and click Create.
    Description of vbcsta_sec3_s4.png follows
    Description of the illustration vbcsta_sec3_s4.png
  5. Drag Call Function from the General actions to the + sign after the Start action.
  6. In the Call Function's Properties pane, click the Function Name drop-down and select setAppLanguage under Page .
    Description of vbcsta_sec3_s6.png follows
    Description of the illustration vbcsta_sec3_s6.png

    This is the JavaScript function you defined in main-start-page.js.

  7. Next to Input Parameters, click the Assign link. In the Assign Input Parameters page, drag the locale parameter from the Sources side to selectedLocale on the Target side. The selectedLocale value is set to the expression $variables.locale. Click Save.
    Description of vbcsta_sec3_s7.png follows
    Description of the illustration vbcsta_sec3_s7.png
  8. Drag Open URL from the Navigation actions to the + sign.
  9. In the required URL field, enter index.html. This navigation will refresh the page after you specify the language. The action chain looks like this:
    Description of vbcsta_sec3_s9.png follows
    Description of the illustration vbcsta_sec3_s9.png

section 4Assign Input Parameters

  1. Click the Page Designer tab. In the Events tab for the English button, the locale input parameter is not mapped. Click the Assign link to map it. If you don't see the locale parameter, refresh your browser.
    Description of vbcsta_sec4_s1.png follows
    Description of the illustration vbcsta_sec4_s1.png
  2. In the Map Variables to Parameters dialog box, click locale under Target. In the Expression area, enter the value for your current locale (en-US, for example) and click Save.
    Description of vbcsta_sec4_s2.png follows
    Description of the illustration vbcsta_sec4_s2.png

    Now you've defined the input parameter for the JavaScript function.

  3. On the main-start page, select the French button, and click the Events tab if necessary.
  4. Click + New Event and select New Custom Event.
  5. In the Select Event dialog box, click Select to select ojAction (the default) under Suggested.
  6. In the Select Action Chain dialog box, select ButtonActionChain and click the Select Action Chain button.
    Description of vbcsta_sec4_s6.png follows

    Description of the illustration vbcsta_sec4_s6.png

  7. In the Events tab for the button, click the Assign link next to Input Parameters.
  8. In the Map Variables to Parameters dialog box, drag a line from detail on the Sources side to detail on the Target side. Next, click locale on the Target side and enter the value for your translated locale, fr-FR, in the expression area. Click Save.

    Both input parameters are now mapped, and both buttons use the same action chain.

section 5Test the Application

  1. Click the Preview Preview icon icon. The application opens in a new browser tab.
  2. On the Departments page, click the French button.

    The page refreshes, and you can see the translated strings.

    Description of vbcsta_sec5_s2.png follows
    Description of the illustration vbcsta_sec5_s2.png
  3. Click Créer. Enter a new department name, select a location, and click Préserver.

    A success message appears briefly, and the new department appears in the table.

  4. Click the Anglais button to return to English. Close the browser tab.

more informationWant to Learn More?