|
|
User's Guide
The Resource Localization Toolset
Version 1.0
Copyright � 1992 Microsoft Corporation
Table of Contents
Table of Contents 1Introduction 2Windows Based Tools: 4RLQuikEd 4RLAdmin 5RLEdit 6DOS Based Tools: 8TokRes 8Update 8Data Files and Data Formats 10Master Project Files (MPJs) 10Project Files (PRJs) 10Master Token Files (MTKs) 10Language Token Files (TOKs) 11Resource Description Files (RDFs) 12Glossaries (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
|
