6 Using String Replacement

All strings used in the portal UI are stored in language files in the PT_HOME\ptportal\version\i18n folder. Using these language files, you can customize existing strings or add new strings to the portal UI.

Each individual language folder within the i18n directory contains a set of xml files specific to a single language. Folders are named according to the standard ISO 639 language code (i.e., de=German, en=English, es=Spanish, fr=French, it=Italian, ja=Japanese, ko=Korean, nl=Dutch, pt=Portugese, zh=Chinese).

The files in each language folder contain sets of strings for specific sections of the portal UI. The most commonly customized files are listed below:

ptmsgs_portaladminmsgs.xml: Strings used in the Administration section of the portal.
ptmsgs_portalbrowsingmsgs.xml: Strings used for most of the messages seen by portal users.
ptmsgs_portalcommonmsgs.xml: Strings used for common messages repeated throughout the portal.
ptmsgs_portalinfrastructure.xml: Strings used in the portal's underlying infrastructure components (i.e., the "Finish" and "Cancel" seen on editor pages).

Customizing Existing Strings in Language Files

The basic procedure for replacing a string in the portal UI is summarized below. See the string replacement examples in the sections that follow for a detailed explanation.

Search for the string in the language folder of your choice. To use Windows Explorer's "Containing text" feature, right-click on the language folder and choose Search....
Open any files that contain the string in a text editor. (The language files have a UTF-8 byte order mark (BOM) at the beginning of each file to help editors identify the file as UTF-8 character encoding. The BOM for UTF-8 is 0xEF 0xBB 0xBF. Use an editor that is capable of reading and writing UTF-8 files.
Replace the string with the message of your choice. Change the text between the <S> </S> tags. Some strings are used in more than one place. As noted above, NEVER change the numbers in the <S> tags or modify the order of the strings in a language file. Also note that XML tags are case sensitive; be careful not to inadvertently change the case of any tag.
After editing an XML language file, view the file in your browser to verify that the XML is well formed.
If your portal is load balanced, you must copy the updated language files to all portal servers.
Restart your application server and restart the portal. If the portal fails to start up, you might have corrupted the language files. It is a good practice to use Logging Spy to watch the portal load the files to verify that the XML files have been edited correctly.

Note: Making changes to one language folder does not change the same string in any other language folder. To internationalize your string replacements, you must add a translated version of the string to the appropriate file in each language folder.

Adding Strings to Language Files

Some customizations require additional UI strings. If your portal supports more than one language, adding strings to the portal XML language files allows your new strings to be localized using the portal's multi-language framework.

Note: To add new strings, use a new XML language file or the SampleMsgs.xml file instead of adding strings to any existing ptmsgs*.xml file. Adding strings to ptmsgs*.xml files can result in string number conflicts.

The sample HTML below can be used in a portlet to retrieve the first string from a new XML language file called my_ messsage_file.xml. The portal knows the locale of the current user and retrieves the string from the correct language folder automatically. (The ".xml" extension is not required when specifying the message file name.) For detailed information on adaptive tags, see theOracle WebCenter Interaction Web Service Development Guide.

<span xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'>
<pt:logic.value pt:value="$#1.my_message_file"/> 
</span>

The GetString method of the ActivitySpace object can also be used to retrieve strings. The ActivitySpace knows the language of the current user; the GetString method automatically retrieves the message from the correct language folder.

The sample code below retrieves the first string from a new XML language file called my_ messsage_file.xml:

import com.plumtree.uiinfrastructure.activityspace.*;
...
public String MyNewCode() { 
myActivitySpace.GetString(1, "my_message_file");
... 
}

Note: To add a new XML language file, you must add the file to every language folder, even if you do not provide translated strings for each language. The portal will fail to load if the XML language files are not synchronized for every language.

Example 1: Hello World Corporation

This example shows how to replace the text displayed at the bottom of all portal pages. As noted earlier, changes to one language folder (in this example, the \en folder) do not change the string for other languages.

In your browser window, copy the string you want to search for.
Navigate to the \en language folder in the \i18n directory.
Right-click on the language folder and choose Search....
Paste the string into the Containing text field and click Search Now.
Open the ptmsgs_portalcommonmsgs.xml file in a text editor.
Search for the string within the ptmsgs_portalcommonmsgs.xml file.
Replace the string with the string you want displayed on each page (for example, "Hello World Corporation").
Save and close the ptmsgs_portalcommonmsgs.xml file.
Restart your application server.
Reload your portal; the new string should appear in the footer at the bottom of the page.

Example 2: Custom Login Instructions

This example shows how to replace the login instructions on the main login page.

In your browser window, copy the string you want to change, for example "Log in to your personalized portal account".
Navigate to the \en language folder in the \i18n directory.
Right-click on the language folder and select Search....
Paste the string into the Containing text field and click Search Now.
Open the ptmsgs_portalcommonmsgs.xml file in a text editor.
Search for the "Log in to your personalized Portal account" string within the ptmsgs_portalcommonmsgs.xml file.
Replace the string with the string you want to appear on the login page, for example "Log in to the Hello World portal account".
Save and close the ptmsgs_portalcommonmsgs.xml file.
Restart your application server.
Reload your portal; the new string should appear on the login page.