Themes Message and Key Files Best Practices and Troubleshooting
Message files contain text fragments (strings) that are presented to the user (for example, the text of buttons or the labels of text fields). You can customize the messages that your users see by changing or adding entries to a message file. (For more details about working with Message files, see in ZWC 5.0, Working with Message Files.)
Keys files contain the ZWC keyboard shortcuts. You can customize existing keyboard shortcuts or add new keyboard shortcuts by changing or adding entries to a keys file. For more information about existing ZWC short-cut keys, see Zimbra Web Client Keyboard Shortcuts.
Both of these files give you additional tools to customize your brand identity and user experience within the Zimbra Web Client. However, changes to any of these files should be implemented with care. This article covers best practices for working with message and keys files, and troubleshooting steps for restoring these files.
During the process of customizing a theme or rebranding, changes may be made to the following message or keys files:
- Message Files
- Keys Files
You should only modify these files if you fully understand how to create ZWC themes. (For more information on creating ZWC themes, see in ZWC 5.0.) If these files are modified incorrectly or are missing entries, your theme can have a variety of issues, including missing text or loss of functionality. This article includes best practices for modifying message or keys files, and includes troubleshooting steps for restoring the above files from backup.
Important: It is not recommended to make theme changes universally. If you need to make changes universally, always have a backup of the file you are changing and always test changes on a test environment before implementing them on a production environment.
The following best practices should be followed to avoid any issues while modifying themes.
- Create a Backup. Before making changes to any of the .properties files, create a backup to restore from in case of any issues. Problems with message or keys files can only be repaired by restoring the file.
- Important: If you do not have a backup to restore from, you must reinstall or upgrade ZCS.
- Make Changes in a Test Environment First. Before making changes to a message or keys file on a production system, use a test system to try out your changes. Any problems with message or keys files can cause major issues on a production system. Testing changes can identify issues before they become a problem.
- Make Changes to Only One Theme. Whenever possible, make changes to a single theme rather than modifying all themes. If you discover an issue with a modified message or key file on a production system, having alternate unchanged themes allows users to continue using the system while troubleshooting the issue.
- Universal Customization to Themes. If the changes that you are making need to be applied universally to all ZCS themes, be sure to append any changes to the end of the file. Because later duplicate entries take precedence, it is always better to add a duplicate message or shortcut to the end of the file and apply changes to that entry rather than altering the original entry.
A variety of symptoms can occur if a message or keys file has been incorrectly modified. Symptoms can include certain features not working, missing text field labels, missing button text, or a range of other issues.
Restoring a Message or Keys File
If you are experiencing issues because of an incorrectly modified message or keys file, you must restore the original properties file from your backup using the steps below. Once restored, the SkinResources servlet automatically appends the skin’s ZmMsg.properties file to the default file.
Important: If you have not created a backup of the properties file, you must either reinstall or upgrade ZCS to restore the message or keys file.
To Restore a Message File
Use the following steps to restore a message file. 1. Move the modified messages to the following location:
2. Restore the original message file from backup to the following location:
To Restore a Keys File
Use the following steps to restore a keys file. 1. Move the modified keys to the following location:
2. Restore the original keys file from backup to the following location:
Related Documents and Articles
- in ZWC 5.0. This comprehensive document includes detailed information about creating and customizing themes in ZWC 5.0.
- Changing the Page Title. This user contributed article provides steps for changing the ZWC page title by modifying ZmMsg.properties.