Localizing text in web applications

You can localize your web application so that the web pages will display in different languages. To localize a web application, you must create a resource bundle for each language that you want to support. These resource bundles contain strings to be presented on the web pages at run time. Each resource bundle is specific to a human language, so that when you switch to a different resource bundle, the strings on the web pages switch to a different language.

You can use translatable strings as the text on web pages. The sections below cover some different uses of these strings on web pages. Also, you can use translatable strings as the error messages for web pages; see Displaying error messages on web pages.

Using translatable strings as output fields

To use a translatable string as the value of a JSF field, such as an output field, you cannot assign the key of the translatable string to an EGL variable bound to the field. To use a translatable string as the value of a JSF field, you cannot bind that field to an EGL variable at all. Instead, you must bind the field to the translatable string directly, as in these steps:

  1. On a JSP file in your EGL web project, drag onto the page a JSF output component, such as an output field, from the Enhanced Faces Components drawer of the Palette view .
  2. Click the field to select it.
  3. In the Properties view, find the Value field. This field shows the text for the component.
  4. Next to the Value field, click the Select Page Data Object button. The Select Page Data Object window opens. Typically, you select a variable from your JSF Handler from this window, but in this case you will use a string from a resource bundle instead.
  5. Go to the String Resource tab.
  6. Click Add Properties File.
  7. In the Choose/Create Properties File window, select the resource bundle file that you want to use on the Existing File tab, or go to the New File tab to create a new resource bundle. In either case, adhere to the naming and placement conventions explained in Creating a resource bundle.
  8. After you have selected or created a resource bundle file, enter a mnemonic to represent the file in the File identifier field. By default, this mnemonic is labels, but if you change it, it must match the mnemonic set in the EGL Page Designer preferences as explained in Setting preferences for web projects.
  9. Click OK to close the Choose/Create Properties File window. The table on the String Resource tab shows the strings from the file. You can use the strings that are already there or add new strings with the Add Resource button.
  10. Select the string that you want to use on the field and click OK. The field shows the key of the translatable string. When you run the page, the server will use the string as the value of the field.

Using translatable strings in EGL properties

You can also use translatable strings as the values of certain EGL properties, most notably DisplayName:

  1. In the jsfhandlers package of your project's Java™ Resources folder, create a resource bundle to hold the strings that you want to use in the application. See Creating a resource bundle. For example, if you are using American English, you might create a resource bundle named myBundle_en_US.properties.
  2. In the resource bundle, add keys and string values for the text that you want to use on the web pages, as in this example:
    myString01=Hello there!
    myString02=Welcome to my Web page.
  3. Set your workbench preferences to use a default mnemonic to represent the resource bundle:
    1. Click Window > Preferences.
    2. In the Preferences window, expand EGL and click Page Designer.
    3. In the Loadbundle variable field, type a mnemonic for the translatable strings. By default, this mnemonic is labels, but if you change it, it must match the mnemonic that is used in the File identifier field in the Choose/Create Properties File window as explained earlier.
    4. Click OK.
  4. In the JSF Handler for the web page, set the DisplayName or Help properties of a variable to the key that represents the text that you want to use on the web page:
    myFieldString string {DisplayUse = button,
        DisplayName = "%myString01",
        Action = "DoSomething"};

    Note the percent sign (%) in the value of DisplayName. This symbol indicates that the value comes from the given key in the resource bundle.

  5. On the JSP that is associated with the JSF Handler, drag the variable onto the page. For example, if you drag the variable in the previous example onto a page, the code created in the JSP is as follows:
    <hx:commandExButton id="buttonMyFieldString1"
        styleClass="commandExButton" type="submit"
        value="#{labels.myString01}"
        actionListener="#{testResourceBundle._commandActionListener}"
        action="DoSomething"></hx:commandExButton>
    Note that the value of the button is not the name of the variable or the value of the variable, but a string from the resource bundle, composed of the mnemonic that you entered in the preferences plus the key that you used in the JSF Handler.

    An alternate method for using the translatable strings on the page is to define a JSF Handler part without an associated page and then allow EGL to create the page based on the variables in the Handler. See "Creating a page from an existing JSF Handler part" in Creating a web page. If you use this method, you can also use a translatable string for the title property of the JSF Handler, and when EGL creates the page, that string will appear prominently at the top of the page.

  6. In the code of the JSP, add the following line of code, directly below the code <f:view>:
    <f:loadBundle basename="myBundle" var="labels"/>
  7. Set the values of the basename and var attributes to the prefix of your resource bundle and the mnemonic, respectively. This example assumes that your resource bundles are named myBundle_locale.properties and that you used the default mnemonic labels.

    This code specifies that the translatable strings represented on the page as labels.keyname are found in the resource bundle files named with the prefix myBundle. The basename attribute of this tag specifies the prefix of the resource bundle file name, and the var attribute specifies the start of the translatable string used in the code.

Using translatable strings for different languages at run time

To use translatable strings for different languages at run time:

  1. Create one resource bundle for each language that your application supports. The file name of each resource bundle in the application must have the same prefix. If the name of your first resource bundle is myBundle_en_US.properties, the names of the other resource bundles must begin with myBundle.
  2. In the Project Explorer view, double-click the file faces-config.xml to open it. This file is found in the folder WebContent/WEB-INF.
  3. Within the <application> tag of the faces-config.xml file, add a <locale-config> tag:
    <faces-config>
    <application>
        <locale-config>
    
        </locale-config>
    ...
    </application
    </faces-config>
  4. Within the <locale-config> tag, add a <default-locale> tag that contains the locale of the default resource bundle. For example, if you want your application to appear in German if the user does not specify a locale or specifies a locale that you application does not support, add the following code within the <locale-config> tag:
    <default-locale>de</default-locale>

    It is good practice to specify a default locale, but it is not required.

  5. Following the <default-locale> tag, add a <supported-locale> tag for each locale that your application supports. For example, if your application supports American English, add the following code within the <locale-config> tag:
    <supported-locale>en_US</supported-locale>
    Following is an example from an application that supports several locales:
    <faces-config>
    <application>
      <locale-config>
        <default-locale>de</default-locale>
        <supported-locale>en_US</supported-locale>
        <supported-locale>es</supported-locale>
        <supported-locale>de</supported-locale>
        <supported-locale>fr_FR</supported-locale>
        <supported-locale>it_IT</supported-locale>
        <supported-locale>pt_br</supported-locale>
      </locale-config>
    ...
    </application>	
    </faces-config>
    If you define a default locale, you must also define that locale as a supported locale.
    Note: Each locale that is defined in this file must have a matching resource bundle defined for that locale.
  6. Save and close the file.
  7. Test your application with your web browser set to different languages to see the different strings.

Feedback