Resource Localization Toolset

The Resource Localization Toolset

Introduction

Windows Based Tools

RLQuikEd

RLEdit

RLAdmin

Data Files and Data Formats


The RL Toolset Team is:

Development:

Steve Blanding

Terry Russel

On-Line Documentation:

Arthur Becker


Resource Localization Quick Editor (RLQuikEd)

Introduction to RLQuikEd

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

File Menu

Glossary Menu

Edit Menu

Operations Menu

Help Menu

See Also

Overview of RLToolset


Glossary Menu for RLQuik Edit
Glossary Menu

The Choose Glossary command allows the user to specify a glossary which can then be used as an aid for translating the resource.  The user must choose a glossary to use the translate and add to glossary buttons.


Operations Menu for RLQuik Edit
Operations Menu

The Resize Dialogs command builds a temporary resource file from the edited tokens, and launches the Windows dialog editor with the temporary resource file loaded.  When the user exits the dialog editor, RLQuikEd will regenerate the token list from the edited resource file.


Introduction to RLQuik Edit
Introduction to RLQuikEd

RLQuikEd is a simple resource editor that allows the user to view the resources contained in a resource file, modify those resources and write the changes back to either the same resource file or a new resource file.  RLQuikEd does not provide any update capabilities and should only be used with resource files that will not be changed.  Due to its simplicity, RLQuikEd is ideal for localizing products that have completed the development cycle.


File Menu for RLQuik Edit
 File Menu

The commands in the File menu operate on resource files

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

Open	Opens a resource file  for editing.

Save	Saves changes made to the current resource file.

Save As	Saves a new document or a new version of an existing document with the file name you specify.

Close	Closes the current file.

Exit	Ends this session

See Also

Keyboard Commands


Open for RLQuik Edit
Open

Opens a resource file  for editing.

Once a resource file has been opened, the localizable resources are displayed in a list box in the main window data area.   Selecting a resource by double clicking or by pressing enter in the list box brings up a dialog box which allows the user to translate the text.  A translate button offers suggested translations for the token taken from the glossary file.  Each time the translate button is pressed a different translation is suggested.  When all translations from the glossary file are exhausted, the original test is displayed.  An add to glossary button allows the selected token's translation to be added to the glossary file.


Save for RLQuik Edit
Save

This operation saves the current open file, and restores to the current state.


Save As for RLQuik Edit
Save As

This operations saves the current open file  using the names indicated by the user.


Edit Menu for RLQuik Edit
Edit Menu

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

Find	Searches for specified text.

Copy	Copies current selection to the clipboard

Paste	Inserts a copy of the clipboard at the current selection.

See Also

Keyboard Commands


Find

Brings up a dialog box that allows the user to search for and modify a given token using any of the token structure fields.


Copy

Copies a token's text into the clipboard.


Paste

Pastes a copy of a previously cut or copied token, into the currently selected token.  This command is unavailable if the clipboard is empty.


Help Menu for RLQuik Edit
Help Menu

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

Help Index	Starts the windows help engine with the RLTools.HLP help file.

About RLEdit	Displays copyright, author and version information.

See Also

Keyboard Commands


Help Index for RLQuik Edit

Starts the windows help engine with the RLTools.hlp help file.


About RLQuik Edit

Displays copyright, author and version information.


Resource Localization Editor (RLEdit)

Introduction to RLEdit

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

Project Menu

Edit Menu

Operations Menu

Help Menu

See Also

Overview of RLToolset


Introduction to RLEdit

RLEdit is a Windows tool that allows a localizer to maintain and localize token files from master token files and source resources.  The localized token files are used to produce localized resources.


Project Menu for RLEdit

The commands in the Project menu operate on project files (PRJ).  A project file contains fields for the master project file, the language token file, the target resource file , and a date stamp indicating the last time the language token file was updated.  Each time a project file is opened or a new project file is created, RLEdit will check to see if the language token file should be updated.  If the master token file has a later date stamp than the date stamp in the PRJ file, the user will be asked if an update should be performed.  If the language token file does not exist then RLEdit will generate the file.

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

New	Creates a new project for editing.

Open	Opens a project for editing.

View	Displays data for selected project.

Save	Saves changes made to the current project.

Save As	Saves a new document or a new version of an existing document with the project name you specify.

Close	Closes the current project.

Exit	Ends this session of TokEdit

See Also

Keyboard Commands


New for RLEdit
New

Creates a new project for editing.


Open for RLEdit
Open

Once a project file has been opened, the token strings in the language token file are displayed in a list box in the main window data area.  Clean tokens are black, dirty tokens are red, and read-only tokens are gray.  Selecting a token by double clicking or by pressing enter in the list box brings up a dialog box which allows the user to translate the token text and mark the text as clean.  A checkbox allows the user to change the read-only status of the token.  The untranslated text is retrieved from the master token file as each token is viewed.  An untranslate button replaces the token's text with text from the master token file.  A translate button offers suggested translations for the token taken from the glossary file.  Each time the translate button is pressed a different translation is suggested.  When all translations from the glossary file are exhausted, the original test is displayed.  An add to glossary button allows the selected token's translation to be added to the glossary file.


Save

This operation saves the current open projects, and saves the current state.


Save As

This operations saves the current open projects  using the names indicated by the user.


Operations Menu for RLEdit

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

Update Tokens	Updates project's language token file.

Generate Resource File	Builds target resource file.

Resize Dialogs	Executes dialog editor so changes can be made.

See Also

Keyboard Commands


Update Tokens

Updates the current project's language token file from the associated master token file.


Generate Resource File

Builds the target resource file  from the language token file.  The current language resource file must be up to date with the resource file for this command to be enabled.


Resize Dialogs
Resize Dialog Boxes

Builds a temporary resource file from the language token file, launches the Windows dialog editor with the temporary resource file loaded, regenerates the language token file from the edited resource file, and deletes the temporary resource file.  The current language resource file must be up to date with the resource file for this command to be enabled.


Help Menu for RLEdit
Help Menu

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

Help Index	Starts the windows help engine with the RLTools.HLP help file.

About RLEdit	Displays copyright, author and version information.

See Also

Keyboard Commands


Help Index for RLEdit

Starts the windows help engine with the RLTools.HLP help file.


About RLEdit

Displays copyright, author and version information.


Resource Localization Admin Editor (RLAdmin)

Introduction to RLAdmin

To get help on a desired menu item, either click the item on the menu below or select one of the names below the menu.

Project Menu

Edit Menu

Operations Menu

Help Menu

See Also

Overview of RLToolset


Project Menu for RLAdmin

The commands in this menu operate on master project files (MPJ).  A master project file contains fields for the source resource file , custom resource description files (RDFs), the master token file, and a date stamp containing the last time the master token file was updated.  Each time a master project file is opened or a new master project file is created, RLAdmin will check to see if the master token file should be updated.  If the resource file has a later date stamp than the date stamp in the MPJ, the user will be asked if an update should be performed.  If the master token file does not exist then RLAdmin will generate the file.

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

New	Creates a new master project file for editing.

Open	Opens a master project file for editing.

View	Invokes a dialog box that displays the data for the selected project.

Save	Saves changes made to the current project.

Save As	Saves a new document or a new version of an existing document with the project name you specify.

Close	Closes the current project.

Exit	Ends this session of RLAdmin

See Also

Keyboard Commands


New for RLAdmin
New

Creates a new master project file for editing.


Open for RLAdmin
Open

Opens a master project file for editing.

Once a master project file has been opened, the token strings in the master token file are displayed in a list box in the main window data area.  Unchanged tokens are black, changed tokens are red, and read-only tokens are gray.  Selecting a token by double clicking or by pressing enter in the list box brings up a dialog box which allows the user to edit the token's status.  A checkbox allows the user to change the read-only status of the token.  A listbox allows the user to mark the token as changed or unchanged.


View

Invokes a dialog box that displays the data for the selected project.


Close

This operation saves all open files, and resets the program to the initial "empty" state.


Exit

Same as the close operation,  only the program is terminated after all open files are saved.


Edit Menu

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

Find	Searches for specified text.

Review	Displays tokens that have changed.

CopyToken	Copies current selection to the clipboard

Copy	Copies current selection to the clipboard

Paste	Inserts a copy of the clipboard at the current selection.

See Also

Keyboard Commands


Review

Brings up an edit dialog box for each token marked as changed since the last update.


Copy Token

Copies an entire token into the clipboard.  This includes the token ID and the token text.


Operations Menu for RLAdmin

The Update command updates the current project's master token file from the associated resource file.

WARNING: since RLAdmin only tracks changes since the most recent update, performing unnecessary updates within RLAdmin can result in a loss of tracking information.  Loosing this information is not fatal but it can be very annoying.

See Also

Keyboard Commands


Help Menu for RLAdmin
Help Menu

To get help on a desired menu item, either click the item on the menu below or select one of the item names below the menu.

Help Index	Starts the windows help engine with the RLTools.HLP help file.

About RLAdmin	Displays copyright, author and version information.

See Also

Keyboard Commands


Help Index for RLAdmin
 Help Index

Displays the help index for this help file.


 About RLAdmin

Displays copyright, author and version information.


Introduction to RLAdmin

RLAdmin is a Windows tool that allows an administrator to maintain master token files from source resources.  The master token files are then used by localizers to produce language token files from which the localized resources are built.


 Introduction

In the past, localization of a software product required the localizer to edit strings and controls embedded in source code and then rebuild the product in order to test the localized version.  Such a process requires at least a rudimentary knowledge of computer programming and is often prone to human error.  The Resource Localization Toolset (hereafter referred to as the RLToolset) was designed to automate localization of products that make use of the Windows resource model by allowing the localizer to extract localizable resources directly from the applications that use them, modify the resources, and use the modified resources to create localized versions of the original applications.  All this can be achieved without rebuilding the product and with minimal knowledge of computer operations.

The RLToolset contains three Windows tools.  These tools provide a complete automated solution in a user-friendly, graphical environment.

The RLToolset was designed with several goals in mind.  Some of these goals were:

Allow the product to be localized without re-compilation.

Allow localization to proceed concurrent with development (provide update capability).

Allow localizers to share glossaries of common terms among applications.

Provide a user-friendly, simple to understand means of localization.

The localization model followed by the RLToolset is very simple.  Localizable resources are extracted from a source resource file and put into special text file called a token file.  Each localizable resource may generate one or more tokens.  Each token is contained on a single line of text and consists of a unique identifier followed by the localizable data associated with that particular resource.  These tokens can then be localized either by using the tools provide by the RLToolset or by using a standard text editor.

The localized tokens are then used in conjunction with the source resource file to generate a new localized resource file.  The target resource file will contain exactly the same resources as the source resource file, the only difference is that the data will be localized.

This model has been expanded a little to allow for update tracking.  When localization is done in conjunction with development a target resource file may change after the localizer has tokenized the file and begun translation.  Update tracking allows the localizer to update the localized token file without loosing any work that might have been done.  Any resources that may have changed since the most recent update are marked "dirty" and the change is tracked in the token file so the localizer may see exactly what changed and exactly how it changed.

To allow for update tracking, the source resource file is used to generate a "master token file" which tracks changes.  The master token file is then used to update any number of "language token files" (one for each target language).  These language token files are then localized and used to generate the target resource files.

This two stage update may seem a little complicated but it results in greater efficiency during the update and it allows a project administrator to preview an update.  During this preview, the administrator may mark tokens as "read only" tokens which the localizer will never need to localize.  The administrator may also mark tokens that have changed very little (perhaps there was a spelling or punctuation change to the original resource) as "unchanged" so the localizer will not need to waste his time re-addressing a token that actually needs no attention.

In addition to the localization paths described above, the RLToolset also provides limited automated translation ability via glossaries.  A glossary is a list of suggested translations for common terms.  Glossaries may be created for each target language and then used for reference during localization.  Any text that has an entry in a glossary may be translated automatically by using one of the suggested translations found in that glossary.

Each of the tools in the RLToolset is described in the following pages.  In addition to the tools described here, the RLToolset uses the Windows Dialog Editor (DLGEDIT.EXE) and the Windows Resource Compiler (RC.EXE) which are also part of the Windows SDK.


Localization

Throughout this help file, the term localization refers to the process of preparing a product for an international market.  This process involves (among other things) translating text and resizing controls such as dialogs and buttons.  A person performing localization is referred to as a localizer.


Resource File

The RLToolset treats any file that contains Windows resources as a resource file.  The RLToolset can use either .EXE files, .DLG files, or .RES files as resource files.

Currently, the RL Toolset only operates properly with Win 3.1 or later .EXEs or .DLLs.  .EXEs and .DLLs built under earlier versions of Windows may not work properly.  We suggest you use .RES files when dealing with projects compiled for older versions of Windows.


Project Administrator

A project administrator would be any person who is designated to maintain a master token file.  If a resource file is being localized for more than one environment, one person should be designated as a project administrator to ensure that the master token file only gets updated when necessary and that each language token file gets updated before the next time the master token file is updated.  This will ensure that the update tracking information does not become inaccurate due to unnecessary updates.  However it should be stated this is actually a very minor problem.  In the event that update tracking information should become corrupted, localized resource data would still remain valid.  The problem will correct itself after the next complete update.


Data Files and Data Formats

The RLToolset uses a variety of special file types.  Every one of the file formats described below is a special form of text file.  Each of the file is human-readable and can be edited with any standard text file editor (such as Notepad).

As a general rule, all text in these files follows the C escape convention when dealing with non-displayable characters.  This convention uses escape characters to represent non-displayable characters.  For example, \n is newline and \t is tab.

See Also

Master Project Files (MPJs)

Project Files (PRJs)

Master Token Files (MTKs)

Language Token Files (TOKs)

Defining Custom Resources(RDF syntax)

Glossary Layout


Master Project Files (MPJs)

Master project files consist of four lines of text:

The first line contains the path to the source resource file.  This may be either a .RES file, a .DLG file or an .EXE file.

The second line contains the path to the master token file (MTK).

The third line contains zero, one or more paths to resource description files (RDFs) separated by spaces.

The fourth line contains a date stamp indicating the date of the source resource file as of the last update.


Project Files (PRJs)

Project files consist of five lines of text:

The first line contains the path to the master project file (MPJ).

The second line contains the path to the language token file (TOK).

The third line contains the path to the target resource file.  This may be either a .RES file or (if the source resource in the MTK is an .EXE or .DLL file) an .EXE file or a .DLL file.

The fourth line contains a date stamp indicating the date of the master token file (MTK) as of the last update.

The fifth line may be left blank or it may contain the path to a glossary file.


Master Token Files (MTKs)

Master token files are text files which contain tokenized resources taken from some source resource file.  Each token consists of a unique identifier followed by the text form of the resource data.  Tokens are delimited by end-of-line characters.

Master token files are used for update tracking.  They contain no localized resource data.

An example of what one token might look like is shown below:

[[5|255|1|32|5|"FOO"]]=Localizable string containing text in C format.

The token ID is surrounded by double square brackets and divided into 6 fields delimited by the vertical pipe | symbol:

The first field indicates the type of the resource

The second field is the resource name in the case of an enumerated resource or it is 255 if the name is a label in which case the label itself is stored in the sixth field.

The third field is the internal resource id number taken from the resource header.

The fourth field is made up of a combination of data taken from the resource header and generated by the tools.  This value is used in conjunction with the other values in the token ID to uniquely identify the resource.

The fifth field is a status field used by the update tools to determine the status of the current token.

The sixth field contains the name of the resource in the case that the resource is identified by a label.  Otherwise it contains a null string.

A token ID is followed by an equal sign which is in turn followed by the resource data.  The data extends to the end of line and is stored using the C escape convention.  Non printing characters (such as new-line and control characters) are represented using C escape sequences.  Two of the most common are \n for new-line and \t for tab.

A token's status field is made up by combinations of  three basic flags:

ST_CHANGED	4	indicates that the token has changed since the last update

ST_READONLY	2	indicates that the token should not be localized.

ST_NEW	1	used in conjunction with the ST_CHANGED flag to indicate whether this is the new or the old version of the token.

For example, if a token has changed during an update, the current text would be stored in a token with a status of  ST_NEW + ST_CHANGED or 4 + 1 = 5.  The previous text is also stored in the token file using the same token ID but the status field would contain ST_CHANGED or 4.  This way both the current and the previous text are retained.


Language Token Files (TOKs)

Language token files are similar to master token files; the only difference being the meaning of the status fields found in the token identifiers.

Language token files are used during localization.  They contain localized resource data.

A token's status field is made up by combinations of  four flags:

ST_TRANSLATED	4	indicates that the token contains text that should be put in the target resource.  If a token is not marked as ST_TRANSLATED then it contains unlocalized text from the master token file which is maintained for update tracking purposes.

ST_READONLY	2	indicates that the token should not be localized.

ST_NEW	1	used only for tokens that are not marked with the ST_TRANSLATED flag to indicate whether this is the new or the old version of the unlocalized token.

ST_DIRTY	1	used only for tokens that are marked with the ST_TRANSLATED flag to indicate that the token is in need of attention (either the original translation has changed or the token has never been localized).

For example, a clean, localized token is marked only with the ST_TRANSLATED flag and therefore has a status value of 4.


 Glossary Layout

Glossaries are sorted text files containing suggested translations for resource data.

Each line in a glossary is divided into four fields delimited by tabs.  The first field is the untranslated text.  The second field is a single character indicating the hot-key (if any) associated with the untranslated text.  The third field is a suggested translation and the fourth field is the hot-key (if any) associated with the suggested translation.

Glossaries may be edited using any good text editor but they are best edited by loading them into an Excel spread sheet.  This way each field occupies a different column in the spread sheet.


Defining Custom Resources (RDF syntax)

Custom resources are described in resource description files (RDFs) using c-like structure definitions.  Each definition may be identified with a specific resource type and id value or a definition may be applied to every resource of a given type.  In cases where both a type definition and a combined id and type definition exist, the more exact id and type definition is given precedence over the more generic type definition.

A resource definition consists of two parts (both of which must be present):  an identifier and a structure definition.  An identifier is declared by the following syntax:

<type>

or

<id,type>

ID's and types are numbers or quoted names UNLESS they are normal windows types in which case the standard Windows type name may be used in place of a number or name. (CURSOR, BITMAP, ICON, MENU, DIALOG, STRING, FONTDIR, FONT, ACCELERATORS, RCDATA, ERRTABLE, GROUP_CURSOR, GROUP_ICON, NAMETABLE, and VERSION).

A structure definition follows normal c syntax with the following limitations and differences:

Each definition must be fully enclosed in braces {  }.

Only standard c types are accepted: char, int, float, long, short, unsigned, near and far pointers.  (Labels and macros are not legal.)

Nested structures, arrays and arrays of structures are legal.  All arrays must have a fixed count except for strings which are described below.  int[10] is legal int[] is not.

Null terminated strings (sz's) are the only variable length structures allowed.  They are represented as an array of characters with no length: char[]

Fixed length strings are represented as arrays of characters with a fixed length: char[10]

Comments may be included in the file using standard c comment delimiters (/* */ and //) or by placing them after the pound symbol #.

Localizable types (types that need to be placed in token files) are indicated by all caps.  Hence INT would generate a token while int would not.

The following is a sample RDF file:

#  This is a sample Resource Description File

<"type"> {

int,	// no token will be generated for this integer

CHAR	// this character will be placed in a token

}

<1000,RCDATA>

{

CHAR[],  // a null terminated string that requires a token

{

int,

FLOAT,	// localizable floating point value

far *,

CHAR[20]	// localizable 20 character string

}[3],	// an array of three structures

int

}


Keyboard Commands for RLQuikEdit

File Menu

CTRL+F12	Open

SHIFT+F12	Save

F12	Save As

ALT+F4	Exit

Edit Menu

F3	Find

CTRL+C	Copy

CTRL+V	Paste

Help Menu

F1	Help Index


Keyboard Commands for RLEdit

Project Menu

CTRL+F12	Open

SHIFT+F12	Save

F12	Save As

ALT+F4	Exit

Edit Menu

F3	Find

F4	Review

CTRL+C	Copy

CTRL+V	Paste

Help Menu

F1	Help Index


Keyboard Commands for RLAdmin

Project Menu

CTRL+F12	Open

SHIFT+F12	Save

F12	Save As

ALT+F4	Exit

Edit Menu

F3	Find

F4	Review

CTRL+C	Copy

CTRL+V	Paste

Help Menu

F1	Help Index