Advanced phrase substitution in UI

This topic describes how to make advanced phrase substitutions.

Fastpath: Admin Console: System > Settings > Phrase Substitutions

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.

In the backend, 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.

Note: Because your phrase substitutions are part of your theme, they are overridden if you change your site's theme. When you upgrade, they are overwritten and you have to recreate them.

Overview of advanced phrase substitution

On the Phrase Substitution Rules page (System > Settings > Phrase Substitutions), you can change the rule or get more information about it.
Advanced Phrase Substitution Rules

On this page you can:

  • Edit an existing rule, specifying which value you're substituting and what you're substituting for it.
  • Add an exception to a rule. For example, you might want to make a substitution everywhere except where the string containing the phrase contains a certain phrase.
  • Delete the substitution rule.
  • View the results of your substitution, seeing the context of your changes — what is actually going to be changed. The rule result list shows which i18n keys your change will affect, as well as the "before" and "after" of the change.
    View Rule Results

Creating new advanced rules

When you need more fine-grained control over your substitution, you can create an advanced rule. You can do this in the Admin Console by editing the custom theme with which the new rule will be associated.

  1. In the Admin Console, go to System > Settings > Themes.
  2. Click the edit icon for the theme to which you want to add the rule.
  3. On the Edit Theme page, click Edit Rules.
  4. On the Phrase Substitution Rules page, click Add Rule.
  5. Configure a new rule for substitution. For each rule specify the following:
    Rule option Value Description
    Target Value or key Whether the rule should be looking for your pattern (what you're replacing) in the i18n values or keys. If you choose Key here, the substitution is for the key's value, not the key itself. This is handy when you know what a particular key is and want to focus on that one in particular.
    Operator Equals, Contains, Starts With, Ends With, or Regular Expression The applied operator
    Pattern The original string. The pattern that should be sought for replacement.

    For example, if you'd specified Regular Expression as your operator, you could enter "\bblog\b" for a pattern that matches the word "blog" (as opposed to "blogger"). The "\b" combination in regular expression can be used to indicate the boundary of a word.
    Replace With The replacement string The text to substitute instead of the text you enter for a pattern.
  6. After you finish, click Save.