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." You can make the substitutions in a simple way for the most common terms. There's also a more detailed way to do it.

    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 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.

    Simple Substitutions

    In the simple way, you can substitute common phrases that are predefined. In the admin console go to System > Settings > Phrase Substitutions. 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 there, 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.

    screen_phrase_subsitutions.png

    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).

    Advanced Substitutions

    On the Phrase Substitution Rules page, you can change the rule or get more information about it. (You can also get to this page from the Themes page by editing a theme, then clicking Edit Rules.)

    screen_substitution_rules.png

    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.
      screen_substitution_results.png

    Creating a New Advanced Rule

    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 theme with which the new rule will be associated. In the console, click System > Settings > Themes, then click the edit icon for the theme to which you want to add the rule. On the Edit Theme page, click Edit Rules. On the Phrase Substution Rules page, click Add Rule.

    When you're adding a rule this way, you'll have four values to enter.

     

     

    Rule Option
    ValueDescription
    TargetValue or KeyWhether 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 will still be 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.
    OperatorEquals, Contains, Starts With, Ends With, or Regular ExpressionThe first four values are self-explanatory. The last specifies that your pattern is a regular expression.
    PatternThe 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 WithThe replacement string.The text to substitute instead of the text you enter for a pattern.