Substituting Phrases in the UI

You can give other names to things people see in the user interface. For example, you can rename "Documents" and "Discussions" to "Articles" and "Conversations." Using the admin console, you can make the substitutions in a simple way for the most common terms.

Admin Console: System > Settings > Phrase Substitutions

Note: This topic describes how to make simple phrase substitutions. For more advanced use of the feature, including more about themes, see the developer documentation.

How It Works

All of your substitutions are made at run time. That is, the application keeps track of what word or phrase you want displayed, then inserts your phrase for the default phrase when someone views a page that includes the phrase. The default phrases themselves come from internationalization (i18n) properties files used for localization. Also, your substitutions are associated with a theme. That means that you can make your substitutions globally or by mapping the change to a particular part of the user interface.

Behind the scenes, your substitutions are remembered as "substitution rules" that use regular expressions. The rules give you a way to fine tune the substitutions to meet your needs.

Making Simple Substitutions

You can substitute common phrases that are predefined. The simple substitution mechanism is designed to account for upper- and lower-case versions of the phrases. However, there are some aspects of the change it doesn't account for. For example, it doesn't account for a change to an article that would precede the word. Substituting "article" for "document" would leave awkward constructions in English, such as "Create a article or upload a file" (where you'd want "Create an article or upload a file"). If you're curious about the outcome of the change you're making, click View Rules to see the rules page, where you can get a preview of what the rule is going (you'll need to save your changes first).

Note: You should always test your changes on an instance of the application that people aren't using day to day. That way, you can work things out before the changes impact the work of others.

To define simple rules:

In the admin console go to the Phrase Substitutions page. There you can choose the theme that the substitution should be a part of and a locale in which the substitution should occur. Beneath these selections you'll see a list of the phrases you can make substitutions for.
If the phrase you want to change is listed on the far left side, enter your alternatives for singular and plural versions of the phrase.
Click Save to make the substitution (you don't need to restart the application or server for the change to take affect).
After you save the rule, you can View Rules to go to the Phrase Substitutions page and see what going on behind the scenes by viewing the details of the substitution rule you're creating.

You won't see the substitution in effect until you assign the theme you select to a part of the user interface. One easy way to verify your work is to assign the theme to the UI application-wide.

Use the following steps to assign the theme to the end user UI globally.

On the Phrase Substitutions page, note the name of the theme you've selected. By default, this is "custom".
In the admin console, go to the Themes page at System > Settings > Themes.
Under Global Theme Map, select your theme (such as "custom") from the dropdown, then click Set Global Theme.

Once your theme is applied as the global theme, you can continue making and testing changes to your phrase subsitutions.