able/windows-nt
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
windows-nt/Source/XPSP1/NT/sdktools/restools/rltools/doc/rltools.txt

613 lines
27 KiB
Plaintext
Raw Permalink Normal View History

Add source files
2020-09-26 03:20:57 -05:00
User's Guide
The Resource Localization Toolset
Version 1.0
Copyright <20> 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
Reference in a new issue Copy permalink