







User's Guide


The Resource Localization Toolset

Version 1.0
























Copyright  1992 Microsoft Corporation


Table of Contents

Table of Contents	1
Introduction	2
Windows Based Tools:	4
RLQuikEd	4
RLAdmin	5
RLEdit	6
DOS Based Tools:	8
TokRes	8
Update	8
Data Files and Data Formats	10
Master Project Files (MPJs)	10
Project Files (PRJs)	10
Master Token Files (MTKs)	10
Language Token Files (TOKs)	11
Resource Description Files (RDFs)	12
Glossaries (TXTs)	13



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 consists of three Windows tools and two DOS tools.  The Windows tools provide a 
complete automated solution in a user-friendly, graphical environment.  The DOS tools provide the same 
functionality at a more primitive level and can be used in conjunction with (or in place of) the Windows 
tools.  Having a set of tools that work from the DOS command line allows much of the localization 
process to be executed by a batch file or during a build script.

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.


Windows Based Tools:

The Windows based tools in the RLToolset provide a completely automated and user friendly set of tools 
for localization.

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.

RLAdmin is a tool that is used by the project administrator to create and maintain master project files 
which track updates and maintain master token files.  This tool allows the project administrator to review 
updates and edit token status fields as desired.

RLEdit is a tool that is used by localizers to create and maintain language project files which track 
updates to the master project files and maintain language token files.  This tool allows the localizer to 
translate tokens and build target resource files.

This section describes in detail each of these three tools.

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.

The RLQuikEd menu is divided into five drop-down menus: File, Glossary, 
Edit, Operations, and Help.

The File-Open, File-Close, File-Save, File-Save As, and File-Exit 
commands all work on resource files (both .RES and .EXE files).  The 
File-Save, File-Close, and File-Exit commands save all work back into 
the original resource file.  The File-Save As command allows the user to 
create a new resource file.

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.

The File-Close command prompts the user to save all work and returns the 
program to its initial "empty" state.  

The File-Exit command performs the same operation as the File-Close 
command and then exits the program.

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

The Edit-Find command brings up a dialog box that allows the user to 
search for and modify a given token using any of the token structure 
fields.  The Edit-Find Next Up and Edit-Find Next Down commands repeat 
the most recent find in the indicated direction.

The Edit-Copy command copies a token's text into the clipboard.

The Edit-Paste command copies text from the clipboard into a token's 
text.

The Operations-Resize Dialog Boxes 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.

The Help-Help Index command displays on-line help.

The Help-About RLQuikEd command displays copyright, author and version 
information.


RLAdmin

RLAdmin (short for Resource Localization Administrator) allows a project 
administrator to create and  maintain master project files which track 
updates and maintain master token files.

The RLAdmin menu is divided into four drop-down menus: Project, Edit, 
Operations, and Help.

The commands in the Project menu operate on master project files (MPJs).  
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 checks to see if the master token file should be 
updated.  If the resource file has a date stamp which differs from the 
date stamp in the MPJ, the user is asked if an update should be 
performed.  If the master token file does not exist then RLAdmin will 
generate the file.

The Project-New, Project-Open, Project-Close, commands all work with 
master project files.

Once a master project file has been opened, the token strings in the 
master token file are updated, if necessary, and 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.  

Note that there are no Project-Save commands.  RLAdmin will 
automatically saves all work when the project is closed, or a new 
project is selected.

The Project-View command invokes a dialog box that displays data 
relating to the selected project.

The Project-Close command saves all work and returns the program to its 
initial "empty" state.  

The Project-Exit command performs the same operation as the Project-
Close command and then exits the program.

The Edit-Find command brings up a dialog box that allows the user to 
search for and modify a given token using any of the token structure 
fields.  The Edit-Find Next Up and Edit-Find Next Down commands repeat 
the most recent find in the indicated direction.

The Edit-Review command brings up an edit dialog box for each token 
marked as changed since the last update.

The Edit-Copy Token command copies an entire token into the clipboard.  
This includes the token ID and the token text.  This is primarily 
supported to allow the entire token to be pasted in a document (such as 
an electronic mail message) for bug reporting purposes.

The Edit-Copy command copies a token's text into the clipboard.

The Edit-Paste command copies text from the clipboard into a token's 
text.

The Help-Help Index command displays on-line help.

The Help-About RLAdmin command displays copyright, author and version 
information.

RLEdit

RLEdit is a tool that is used by localizers to create and maintain language project files which track 
updates to the master project files and maintain language token files.  This tool allows the localizer to 
translate tokens and build target resource files.

The RLEdit menu is divided into four drop-down menus: Project, Edit, 
Operations, and Help.

The commands in the Project menu operate on project files (PRJs).  A 
project file contains fields for the master project file, the language 
token file, the target resource file, a date stamp indicating the last 
time the language token file was updated, and an optional glossary file.  
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 date stamp which differs from the date 
stamp in the PRJ file, the user is asked if an update should be 
performed.  If the language token file does not exist then RLEdit 
generates it.

The Project-New, Project-Open, Project-Close, and Project-Save commands 
all work with project files.  

When a project file is opened the tokens are checked to see if they must 
be updated.  If they need to be updated then RLEdit updates the tokens 
automatically.

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 (tokens which have not been 
translated since they last changed) 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 check box 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.

RLEdit automatically saves all work whenever the dialog editor is 
started, when a target file is generated, when a project is closed, or 
when a new project is opened, however the Project-Save command may be 
used to save work in progress at any time without leaving the selected 
project.

The Project-View command invokes a dialog box that displays data about 
the selected project.

The Project-Close command saves all work and returns the program to its 
initial "empty" state.  

The Project-Exit command performs the same operation as the Project-
Close command and then exits the program.

The Edit-Find command brings up a dialog box that allows the user to 
search for and modify a given token using any of the token structure 
fields.  The Edit-Find Next Up and Edit-Find Next Down commands repeat 
the most recent find in the indicated direction.

The Edit-Review command brings up an edit dialog box for each token 
marked as changed since the last update.

The Edit-Copy Token command copies an entire token into the clipboard.  
This includes the token ID and the token text.  This is primarily 
supported to allow the entire token to be pasted in a document (such as 
an electronic mail message) for bug reporting purposes.

The Edit-Copy command copies a token's text into the clipboard.

The Edit-Paste command copies text from the clipboard into a token's 
text.

The Operations-Generate Resource File command 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.

The Operations-Resize Dialog Boxes 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, RLEdit will regenerate the token list from the edited resource 
file.  The current language resource file must be up to date with the 
source resource file for this command to be enabled.

The Help-Help Index command displays on-line help.

The Help-About RLEdit command displays copyright, author and version 
information.




DOS Based Tool:

The DOS based tool (TokRes in the Win16 version and RLMan - see RLMAN.DOC - in the Win32 
version) duplicates the update, automated translation, tokenization, and resource generation functions of 
the Windows based tools.  It may be operated from the command line, via batch files, or via build scripts.  
The most common use for the DOS based tool is to eliminate the need to use RLAdmin for updating 
master token files but it can be used (in conjunction with a text editor) to take the place of all of the 
Windows based tools.

TokRes

TokRes is a tool for merging and extracting tokens to and from resource files.

The syntax of the TokRes command is as follows:

Usage: TokRes [-c <RDF_file>]  -{h|e|t|r} <files>

	-h						Print usage message
	-e <Input_exe_file> <Output_res_file>		Extract resources 
from an exe to a res file.
	-t <Input_res_file> <Ouput_tok_file>		Build token file 
from exe or res file
	-r <Input_res_file> <Input_tok_file> < Output_res_file>	Build 
res or exe file.
	-c RDF_file 			Use custom resources defined in 
resource description file



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.

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 file) an .EXE 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.


Resource Description Files (RDFs)

Custom resources are described in resource description files (RDFs) 
using c-like structure definitions.  Each definition is identified with 
a specific resource type and the definition is applied to every resource 
of that given type.

An identifier is declared by the following syntax:
<type>

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 {  }.
*	The following data types are accepted: char (single-byte character), 
wchar (Unicode character), tchar (same as wchar in NT version of 
tools, same as char in Windows 3.1 version), int, float, long, short, 
unsigned, near and far pointers.  (Labels and macros are not legal.)
*	Nested structures and arrays are legal.  All arrays must have a fixed 
count except for strings which are described below.  int[10] is legal 
whereas 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 single-byte character will be placed in a token
	}
<RCDATA> {
	WCHAR[]  // a null terminated Unicode string that requires a token
	wchar[]  // no token will be generated for this Unicode string
	}
<1000>
	{
	TCHAR[],  // a null terminated Unicode or OEM string that requires
                // a token (Unicode if running NT version, else OEM).
		{
		int,
		FLOAT,	// localizable floating point value
		far *,
		CHAR[20]	// localizable 20 character single-byte string
		}[3],	// an array of three structures (NOT IMPLEMENTED YET)
	int
	}
END

Glossaries (TXTs)

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.

 Throughout this document, 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.
 This document refers to a resource file as being any file that contains Windows resources.  This can be a 
Windows executable format file as well as a .RES file.  The RLToolset can use either .EXE or .DLL files 
or .RES files as resource files.
 A project administrator is 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.
 This document refers to a resource file as being any file that contains Windows resources.  This can be 
an .EXE file or a .DLL file as well as a .RES file.  The RLToolset can use either .EXE files, .DLL files or 
.RES files as resource files.  Currently we only support Win 3.1 .EXEs and .DLLs.  .EXEs and .DLLs 
built under Win 3.0 may cause errors.  We recommend using .RES files for earlier projects.
1


