PRBEditor

User manual for version 0.9.7

Contents

I.Introduction
II.Features
III.Installation
IV.System files tree view
V.More on Filters
VI.More on Bookmarking
VII.More on Views
VIII.More on Translator
IX.More on Spell Checker
X.The HTML special characters Converter
XI.Merging of Resource Sets
XII.Application Menu
XIII.Integration with Eclipse 3.1
XIV.Integration with NetBeans 5.0

Introduction To the top

PRBEditor makes it easy to manage properties files, those used by the Java language class java.util.PropertyResourceBundle. The program may show more than one language in a table, where there is a row per key and a column per language.

A properties' file name is made of a base prefix, a language code and the fixed suffix ".properties"

<base-prefix>[ _languageCode].properties
The language code is optional. It is recommended that a properties file without a language code exists, as this is the file where the program will look for untranslated strings. Therefore, this base file should contain default values for every internationalized string. PRBEditor will perform much better if the base file exists. It is advisable, when openning a resource file within PRBEditor, to choose a base properties file. In this case, the program will automatically find and open all the available translations.

Features To the top

Installation To the top

To run the application, you'll need a Java Virtual Machine version 1.4 or 5 (1.5) already installed in your computer. If you don't have one, you can download it from www.java.com The application doesn't have any installer to run. Once it has been downloaded, unzip it in your desired folder. The executable file is prbeditor-xxxx.jar, where xxxx is the version of the applicacion you downloaded. In MS Windows OS it should be enough to double click this file to run the application, but sometimes this system doesn't work. In this case and for other operating systems, the application can be started from the command line with the following command:

<Java VM install directory>/bin/java -jar prbeditor-xxxx.jar [file-to-open]

The aplication saves its configuration files in the working folder, and that usually is the folder from where you started the application. You can have multiple configurations if you run the application from different folders.

To uninstall the application, just remove the downloaded and unzipped files along with the configuration files.

System files tree view To the top

Starting in version 0.9.6 a left-sided pane has been added. This pane shows in a tree the system folders and the properties files available in them. Right clicking on a file or folder will pop up a context menu. This menu has the options to open a properties file or create a new one. It also offers the possibility to select a folder as the root of the view. If this option is selected, then the pane will only show the files and subfolders of the selected folder. Once this option is set, the first folder shown in the pane will represent the parent folder of the current folder. Double-clicking on this folder will set as root folder the parent file of the current root folder. The last option, named Select Opened, searches, makes visible and selects in the tree the properties file currently opened. Double-clicking on a properties file will also open that file.

More on Filters To the top

Filters are a tool provided to restrict the lines/rows the application shows to the user. Its usage is specially useful when dealing with big files and when strict naming rules are applied to organize the keys in our resource files. For example, let's say we always use the prefix menu for all keys related to resources used in the application menu, and the suffix icon for all those keys whose value is a link to an image. We could force the application to only show menu keys by creating and applying the filter menu.*. Alternatively, we could force the application to only show image links by creating and applying the filter .*icon

Filters are regular expressions. The syntax is the same used by Java's regular expression engine. Limited information about the syntax can be found here.

Filters might be given a name so they can be stored and reused later on.

More on Bookmarking To the top

A bookmarked row displays a flag on the left hand side of the key cell. Besides, the area to the right of the vertical scroll bar is used to paint a rectangle for each bookmarked row. Left clicking on any of this rectangles will scroll to the represented bookmark. Right-clicking will popup a context menu containing bookmark related actions.

There are two kinds of bookmarks: filter based and key based. The former will bookmark all rows whose key matches a given regular expression. The later will bookmark those rows whose keys have been selected by the user.

More on Views To the top

A view is a Tab Panel that shows the contents of the opened resource files. Each view:
Let's say we use some naming rules to organize the keys in our resource files. For example, we always use the prefix menu for all keys related to resources used in the application menu, and the suffix icon for all those keys whose value is a link to an image. In this scenario we could create two views: the first would show the menu related data (with the filter menu.*); the second would show all image links (with the filter .*icon). Those images used in the menu would have both, the menu prefix and the icon suffix, and thus would appear in both views.

Note: a line/row inserted in any view will appear in all other views regardless of the filter each view has applied. So, the views might need to be refreshed in other to show only what the filter defines.

More on Translator To the top

This version of PRBEditor includes a simple translator between English, Catalan and Spanish languages. It is only useful for simple common words like File, Copy or Cancel. When the user starts editing a cell, the application tries to infern the proper value by looking at the values of other languages for the same key. If any option is found, a popup with a list containing all possible values is opened. The user can change the selection in the popup list by using the up and down arrow keys or the mouse. To use one of the proposed values, it is as simple as hitting the Enter key. To accept the current contents of the cell without using any of the values in the popup, just hit the Tab of F2 keys.

The application suposes that the language of the default resource file (that without locale suffix) in English. If that's not the case, this default language can be changed by modifying the file conf.properties, located in the application working directory, and created automatically if it can not be found when the application is run. This file is a common properties file, and the line to change looks like defaultLanguage=en.

More on Spell Checker To the top

This feature is by default disabled, since the application is distributed without dictionaries, due to their size. A dictionary is simply a text file containing a list of valid words in lower case. Dictionaries for some languages have already been compiled and are available for download from the application web site.

To enable the spell checker, just open the Preferences form and select the list item named Spell Checker. The panel on the right will show all the configuration options. In addition to the enable/disable check box, the panel accepts a list of patterns the keys of the rows must match so its cells may be spell checked. It is alo possible to specify a list of patterns the keys of the rows can not match to be spell checked. Thanks to this mechanism the user can control which rows may be checked, saving those cells that don't hold regular text, like references to resources like images for instance. The rows whose cells are eligible for conversion will show this icon in the key cell. Finally, the Dictionaries tab shows a list of all locales for which a list of valid words exist. The two buttons allow to index new dictionaries and remove existing ones. It is possible to index more than one dictionary for a given locale, in which case a union will be made.

Once the spell checker is enabled, the engine will mark those words not recognised with a wavy red underline, and only for those languages with an indexed dictionary. Right-clicking on one word, and when the cell is in edition mode, will popup a list of suggested similar words. Any word selected from this list will replace the original word. Note that it doesn't matter whether the word is marked as wrong or not. It is always possible to trigger the popup of similar words as long as a dictionary for the language of the column has been indexed.

Spell Check Dialog

The Spell Check Dialog can be used to traverse the whole properties file to find and correct spell mistakes. For each mistake found a list of alternate words is shown. The user can choose one of these words to replace the mistaken one. The user can also rewrite the word or ignore it. The ignore option may be valid only for the current operation or the word may be added to a list of words to be ignored always. This list of words is stored in a file called wordsToIgnore.xml, which is created on the application's first run. The file may contain several lists of words, each one applying to one locale or to all locales.

The HTML special characters Converter To the top

The HTML converter can automatically substitute html special characters into html codes. It can also show the special characters instead of HTML codes to easy the reading of cell values. The HTML converter is disabled by default. It can be enabled from the preferences form. The converter can be configured to only monitor those cells whose key matches or not user defined regular expressions. The rows whose cells are eligible for conversion will show this icon in the key cell. The converter only works at the time of cell edition. When the user edits a cell (using the default editor or the pane editor) that is selected as being monitored by the HTML converter, all the typed special characters will be converted to HTML codes once the edition stops. The converter will not convert special chars when a file is opened or closed, only when a cell is edited. Not all special characters are translated. The following ones still need to be coded manually: &, ", <, > The full list of converted characters can be seen in the Preferences Form, HTML Converter option, Conversion Table tab.

The option of showing special characters instead of codes works independently of whether the converter is enabled or not. Those characters affected by this option will be marked with a green line above them.

Merging of Resource Sets To the top

Starting from version 0.9.7 the application includes a tool to merge the currently opened resource file set with another one in the file system. This tool is available in the application File menu and in the context menu of the left-sided file system pane.

The Merge Form compares the two resource file sets and shows a tab for the new entries, the deleted ones, the new locales and the changed values. In each tab the user can select those entries to be added, removed or changed.

The last tab requires the user to select a locale so it can perform a translation-file to translation-file comparison. Only those locales common to both resource sets are shown.

When the Merge Form is closed, the added and changed keys are bookmarked so the user can review the changes made. This changes are not undoable through the application build-in Undo tool, so to discard the changes the user can only exit the application without saving.

Application Menu To the top

Integration with Eclipse 3.1 To the top

There are two ways to integrate prbeditor with eclipse 3.1, as an external editor or as an external tool. The later is easier to do, but the former provides better integration and comfortability. Below you'll find detailed instructions for both ways. Both have been done in the windows version of eclipse 3.1

Integration as an external tool

  1. Open the External Tools management window, under the menu Run/External Tools/External Tools
  2. Create a new Program configuration
  3. Configure the new program as in the picture below

    Location: path to the java VM launcher
    Working Directory: where the program will store the configuration files
    Arguments: replace <prbeditor-install-dir> for the folder where you unzipped prbeditor

  4. To edit a resource using prbeditor, from the view Package Explorer or Navigator select the master resource to edit and run the external tool just created

Integration as an external editor

  1. Create a DOS bat file containing the following commands:
    cd <folder-where-to-store-config-files>
    <java-install-dir>\bin\java -jar "<prbeditor-install-dir>\prbeditor-0.9.5_7.jar" %1
    For linux, just create the equivalent commands in a sh file (sorry, I don't know them)
  2. Open the eclipse's Preferences Window and, inside it, select the General/Editors/File Associations editor

  3. In the File Types list, select *.properties. You may have to add it if it is not already there
  4. In the Associated Editors list, add the bat file just created
  5. Accept the changes
  6. From now on, you should be able to edit your resource files with prbeditor. The name of the bat file you created should appear in the file context sub-menu Open With. From the view Package Explorer or Navigator, right-click on a resources file to be edited and select the sub-menu Open With

Integration with NetBeans 5.0 To the top

To be able to launch prbeditor from NetBeans 5.0, just download and install the Netbeans module from prbeditor's web site. The module, once installed, adds an option to .properties files context menu that opens the file in prbeditor. The application must be downloaded and installed separately.

To configure the module, go to Tools/Options/Miscellaneus/Prbeditor. Once there you must specify the installation folder of prbeditor application, the java VM home folder and, optionally, the folder where to load/store prbeditor's configuration files