Customizing user interface messages and text

Zoom 6.0, and above, supports customization of user-interface messages and text. If you are unsatisfied with the language of any particular installed message or text, you can make it more refined, easy to understand, or, relevant to your organization.

This customization is meant to be performed by advanced users or system administrators.

These custom messages are stored in the form of text files, referred to as message catalogs or properties files. A message is identified by its pre-defined message key, and its corresponding message text is defined in the message catalog.

The next section discusses where these message catalogs can be created or edited, followed by a section on how individual message texts are defined. The final section summarizes the process of how to perform message or text customization.

 

Layout of Custom Message Catalogs

The catalogs are present in 2 different locations: one for custom changes, and another for installed messages.

  1. The custom location is:
    • <ZOOM_INSTALL_DIR>/conf/resources/
    • This is for making custom changes to the deployments.
    • The location is designed to not be over-written on installation of updates etc.
  2. The install-specific location:
    • <ZOOM_INSTALL_DIR>/lib/zoom/resources/
    • This is to be used as a reference for the installed messages and message keys.
    • The location is designed to be automatically updated i.e. over-written on installation.

Within the resources directory, the properties files for different modules and bundle-names are organized into sub-directories.
The scheme for the module and bundle organization is:
    <module-name>/<bundle-name>/

Module-wise layout

  • Java zoom module:
    • For zoom server, preview server and command-line client.
    • module-name = zoom
    • no bundle-name.
    • So, properties files stored in the directory: resources/zoom/
  • Java GUI client module:
    • For Java GUI clients –
      • ClientProxy: Z-icon and Finder/Explorer context menu
      • GUI dialogs like Settings, Repository Browser, Update, Checkout.
    • module-name = javagui
    • no bundle-name.
    • So, properties files stored in the directory: resources/javagui/
  • Flex GUI clients:
    • For the Flex GUI clients:
      • the Asset Browser (desktop and web)
      • Flex dialogs like Check-In dialog
    • module-name = zmflex
    • bundle-name = eng_US
    • So, properties files stored in the directory: resources/zmflex/eng_US/

Properties files

Finally, the message properties are defined in a custom-messages properties file.

Properties file naming

A property file holding such custom messages is named as:
    custom-messages_<language-code>.properties

For example, an english language messages file is named:
    custom-messages_en.properties

Some example langauge-codes are:

  • English: en
  • Spanish: es
  • French: fr
  • German: de

So, for a customized Spanish-language properties file for the Flex GUI clients:

  • File name: custom-messages_es.properties
  • Module directory: zmflex/eng_US/
  • Base directory: <ZOOM_INSTALL_DIR>/conf/resources/
  • So, full file path will be: <ZOOM_INSTALL_DIR>/conf/resources/zmflex/eng_US/custom-messages_es.properties
Reference files

For reference purposes, the properties files that are compiled in the various distribution modules are provided in the install-specific location described above, with the additional suffix .compiled to clearly disambiguate them from the deployment-specific files. Thus, these files are named as:
    custom-messages_<language-code>.compiled.properties
So, the packaged French-language properties file for the Java GUI clients would be:
    <ZOOM_INSTALL_DIR>/lib/zoom/resources/javagui/custom-messages_fr.compiled.properties
These files are only provided for reference, and any changes made to them will not be used by the Zoom system.

Additional installed properties files

Additionally, installed properties files i.e. those located in the install-specific location described above, which contain messages that override those in the pre-compiled reference files above, are named with an additional suffix .default. Thus, these files are named as:
    custom-messages_<language-code>.default.properties

 

Properties file contents

These custom properties files are meant for adding to or over-riding any existing messages. So, only those message keys and their values need be defined in the custom properties file. Any other messages which are unchanged from the existing form need not be added to these files.

The file is structured in a simple manner of resource message key = message string text. This is exactly the same format that the compiled properties files have i.e. the Java properties file format. Some salient features are:

  • Example property message:
        FONT_SIZE = Font Size
  • Special characters like new-lines, tabs, forward-slashes etc. must be written in escaped form i.e. with a preceding forward-slash. Examples:
    • New-line: \n
    • Tab: \t
    • Forward-slash: \\
    • Double-quote: \"
    • Single-quote: ''
  • For easy readability, a message string could be split over multiple lines, with a \ character at the end of each continuing line. E.g.:
        FILE_BROWSE_POPUP_TITLE=Assets \
             to \
             check-in.
    This will create the message “Assets to check-in.” without any of the continuing line characters.
  • The message strings should conform to ISO-8859-1 encoding.
    • Unicode characters must be in UTF-8 encoding, but written in code point form. E.g.:
      • Small letter n with tilde: ñ, is written as its UTF-8 code point (00F1): \u00f1
      • Long em-dash: , is written as: \u2014
      • Small e with acute: é, is written as: \u00e9
      • Character to UTF-8 code-point conversion may be done easily using online tools like: http://www.ltg.ed.ac.uk/~richard/utf-8.cgi
 

Recommended method to customize messages

  1. Identify which module(s) the message to be modified may belong to.
    • Find the module for the client Zoom application in the modules list above.
    • Further, the message may also be from the Zoom server module, if it is being shown as an alert after performing an operation that communicates with the Zoom server.
    • This step may be skipped if using the second option given below for identifying the message key.
  2. Identify the message key.
    • Search for the message text (or parts of it) in the module and language-specific reference properties file(s).
    • Alternatively, search for the message text (or parts of it) in all files in the install-specific location using an advanced editor, like Notepad++, or an advanced terminal command, like grep.
    • The message key is the string at the beginning of the line, before the =, and is usually in ALL CAPS.
  3. Create the directory in the custom location, if absent, for the custom message bundle of the module identified above.
  4. Create an empty file, if absent in the directory above, for the properties file for the required language.
  5. Open the above custom properties file in a text editor, and add a new line to it with the above identified message key = the new message text.
  6. Save the edited file.
  7. Restart the Zoom client application, or Zoom ClientProxy (or Zoom server in case the message was in the server module), for the change to take effect.

Example process flow

Suppose, we want to change the english message shown when searching in the Asset Browser for some criteria which does not match any asset. The message being shown by default is “Oops! no matches found for the given criteria.”, and the new message required is “No matches found!”.

  1. Module sub-directory:
    1. The message is showing in the Asset Browser, but is also an alert after communicating with the server.
    2. So, possible modules could be Flex GUI client, or Java zoom.
    3. So, module directories could be either zmflex/eng_US, or, zoom, respectively.
  2. Message key:
    1. Language of the message text being modified is English, i.e. language code: en
    2. In a text editor, open the reference files for the above modules and English. The files would be:
          <ZOOM_INSTALL_DIR>/lib/zoom/resources/zmflex/eng_US/custom-messages_en.compiled.properties
          <ZOOM_INSTALL_DIR>/lib/zoom/resources/zoom/custom-messages_en.compiled.properties
    3. Search in the files opened above for the text “Oops! no matches”.
    4. The searched text is only found in the zoom module property file.
    5. The line containing the searched text is:
          NO_RESULT_FOUND=Oops! no matches found for the given criteria.
    6. So, the message key is: NO_RESULT_FOUND
  3. Create custom module directory, if it doesn’t exist:
        <ZOOM_INSTALL_DIR>/conf/resources/zoom/
  4. Create an empty file custom-messages_en.properties, if absent in the directory above.
  5. Open this custom-messages_en.properties file and add the new line for the message key to it:
        NO_RESULT_FOUND = No matches found!
  6. Save the properties file.
  7. Restart the Zoom ClientProxy and Asset Browser.

For adding unsupported languages: Say for the German language, a custom_messages_de.default.properties file should be added at <ZOOM_INSTALL_DIR>/lib/zoom/resources/ location in each respective module structure. The new custom_messages_de.default.properties file must have all the message keys defined, that are present in the reference file custom_messages_en.compiled.properties.

Leave a Comment