SuiteFactory Localization Features

Version 7.0.182 and later

Introduction

In 2001, CCI localized an earlier version of SuiteFactory to the Chinese (PRC) locale (MS Windows locale id 2052 decimal or 804 hexadecimal). Several issues made localizing the product quite difficult, and these same issues have made updating the translation difficult. Specific issues include:

·         The localizing translator, who was an employee of the end user company in the PRC, did not have access to software that could directly edit the Microsoft resource files used by our software.

·         Instead, the translator had to work with Unicode text files that needed to be returned to CCI for additional processing. CCI had to cut and paste the translations into resource script files that were then compiled into resource files.

·         The string resources were compiled into executable files. Any change to the translation required recompiling the application and building a new installation set.

For these and other reasons, CCI decided to redesign its text resource system and include a translation module that would permit a translator to use SuiteFactory directly to complete the translation and verify the results. A customer site could also use the same tool to customize the user interface text to local requirements, or to produce its own translation to a local language from the English original.

This document describes the new localization features of SuiteFactory.

 Using the Translation Feature

SuiteFactory works best when the Windows system locale and user locale are the same and when the installation set has been targeted for the same locale. For example, to use Simplified Chinese text instead of US English text, it is best to install the Simplified Chinese installation set for SuiteFactory, and to configure both the system locale and the user locale to Chinese (PRC).

If you are using Windows 2000 or later, it is possible to successfully install the US English installation set for SuiteFactory and successfully run it under a different locale and have the system display SuiteFactory text in the local language, provided that a localization file exists for the current locale. If no localization file exists, the system will display the default US English text.

This document uses the Chinese (PRC) locale as the example for using the SuiteFactory translation feature.

Background

All user interface text for SuiteFactory is now stored in a collection of string resource files. These files are stored in the path where SuiteFactory is installed inside a sub-folder named "Resource". There are 2 classes of files:

·         Definition files contain the definition and description of each string resource, which includes the id number, description, whether it can have more than one line, whether it can contain tab characters, whether it can include a shortcut character, and whether it can contain any parameters for values that are calculated while the program runs. CCI determines the contents of the definition files.

Definition files have names with the format SFRx.CCD, where:
-"x" identifies a specific resource set.

·         Text files contain the text value for each string resource for a particular locale. Text files come in 2 flavors: default text files, and edited text files. Default text files are shipped as part of the SuiteFactory installation set. Edited text files are created by SuiteFactory users with the new translation/localization features.

Every SuiteFactory installation set includes at least the default text files for US English (locale id 1033 decimal or 409 hexadecimal). CCI may also include default text files for other locales. CCI determines the contents of the default US English text file.

Default text files have names with the format DSFRx<locale id>.CCR, where:
-"x" identifies a specific resource set, and
<locale id> is the hexadecimal representation of the locale id for the locale that the file targets.

Edited text files have names with the format ESFRx<locale id>.CCR, where:
-"x" identifies a specific resource set, and
<locale id> is the hexadecimal representation of the locale id for the locale that the file targets.

When SuiteFactory starts running, it opens and reads into memory all of the available definition and text files that are present and valid for the current system and user locale.

Whenever SuiteFactory needs to display text in the user interface, it fetches the correct text value by using the string's ID number to look up the text value in one of the text files, then replacing any substitution parameters with the current values, then displaying the text. SuiteFactory always checks the text files in a specific order, and always uses the first valid text value that it finds. The order is:

·         The edited text file for the current locale.

·         The default text file for the current locale.

·         The edited text file for the US English locale.

·         The default text file for the US English locale.

Starting a translation

Before starting a translation, you must:

1.        Install and configure SuiteFactory on the computer. (This includes configuring the path to the SuiteFactory database and registering the computer as a SuiteFactory workstation.

2.        Use the Regional Options applet in the Control Panel to set the system locale and user locale to the locale for which you wish to create a translation. Also make sure to install any keyboard drivers or input method editors that you may need for entering text for the target locale. Reboot the computer if necessary.

To work on the translation for the current system/user locale, you should:

1.        Start SuiteFactory, and log in under a user name that has the right to run the language translation feature.

2.        Click the menu item "Configure -> Configure Language" to display the language configuration window. Make sure that the current language mode is set to Local Language or to Local Language and English, either with or without the Resource Id. (This will allow SuiteFactory User Runtime to automatically update the user interface text with your translation after you save your edits and close the translation window.) Save any changes and close the window.

3.        Click the menu item "Configure -> Translate User Interface Text" to display the translation window. This will display the Manage String Resources window for translating to the current locale. (See Figure 1.)

4.        The Manage String Resources window displays several columns

Id: The unique numeric id for the string resource.

Default text: The default English (United States) text for the string resource.

Edited text: The current text for the string resource. The column heading specifies the language and locale for this translation. The text is the current value that SuiteFactory displays; the text may be the edited translation, or it may come from

String Source: The identification of the text file in which SuiteFactory found the current text displayed in the edited text column. Possible values include the following:

Local Edited: Your current translation for this text item.
Local Default: The current translation supplied in the default text file for the current locale.
English Edited: Your current US English replacement text for this text item.
English Default: The default text for this item as determined by CCI.

5.        Scroll through the list of string resource to locate and select the item that you wish to translate or edit. You can select an item either by using arrow keys to move up or down or by clicking on a row with the mouse (or other pointing device).

6.        Open the selected resource for editing by doing one of the following:

·         Pressing the Enter key

·         Double click on the row for the item you wish to edit

·         Select the menu item "Edit -> Properties"

7.        SuiteFactory will display the Translate String window. (See Figure 2 and Figure 3.)

The Translate String window

The Translate String window allows you to define a new value to use in place of the default value for the selected SuiteFactory string. The window displays a variety descriptive information about the string and the context in which SuiteFactory uses it, as well as descriptive information about substitution parameters that SuiteFactory expects to replace with actual values when it displays the text.

The description information includes the following items that CCI sets and that you cannot modify:

Id: The ID number for this string.

Description: A brief description of the use or context for this string.

Original Text: The text for this string as stored in the default US English text file, and the properties of the string in that file.

If other text files also contain values for this resource, they are available by selecting the text file from the drop-down list.

Parameters: A list of the substitution parameters that SuiteFactory expects for this string. Each entry includes a description of what value the parameter represents.

Translation: This area includes a text box where you can enter your translation, as well as other buttons and lists for specifying a short-cut character or inserting tab characters or substitution parameters.

There are some rules for what text you can enter in the Translation text box. They include:

·         If the caption "Multiline" appears below the text edit box, then the string may contain more than one line of text. If the text edit box has the keyboard focus, typing the Enter key will insert a newline character at the current cursor location.

If the caption "Single line" appears below the text edit box, then the string must be one line only.

·         If the caption "Allow tab characters" appears below the text edit box, then you may insert a tab character into the string at the current cursor location by clicking the button named "Insert Tab".
(Typing the Tab key always moves the keyboard focus to the next widget in the window.)

If the caption "Prohibit tab characters" appears below the text edit box, then SuiteFactory expects that the string will not contain tab characters, and you are not allowed to insert them with the "Insert Tab" button.

·         If the string "Shortcuts enabled" appears to the right of the text edit box, SuiteFactory uses this string in a context that supports shortcut characters, and you are allowed to define a shortcut character for this item. (See section 2.4, About Shortcuts)

If the string "Shortcuts disabled" appears to the right of the text edit box, SuiteFactory uses this string in a context that does not support shortcut characters.

·         If the string has a defined set of associated substitution parameters, you can insert an instance of a particular substitution parameter at the current cursor location by selecting the entry in the parameter list and then clicking the button labeled "Insert Parameter".  (See 2.5, About Substitution Parameters)

About Shortcuts

Most applications that run on Microsoft Windows platforms require that a user navigate from one object to another in the application's windows. Most programs support several methods of navigation:

·         pointing and clicking with a mouse

·         moving from one object to another by using arrow keys, the tab key and the enter key

·         typing the <Alt> key followed by the key for the "shortcut character" of the menu or command button you want to invoke or of the data entry object you want to go to.

If a navigation target on a window has an associated shortcut character, the character appears in the object's label marked with an underline or some other indicator that makes it stand out.

SuiteFactory string resources that are used as labels for objects that can have shortcut characters are marked with the caption "shortcuts enabled". These resources allow the translator to define the shortcut character for the string as well as define where the shortcut character appears in the string.

If a string resource can specify a shortcut character, then SuiteFactory treats the ampersand character (the character &) as a special character. There are two cases:

·         "&&" (two & in a row) tells SuiteFactory to display one '&' at that position in the string.

·         "&" followed by any other character tells SuiteFactory to hide the "&" and underline the following character. If you use '&' this way two or more times in a string, SuiteFactory ignores all of them except the last one, and only the character that follows the last '&' is underlined.

The only characters that are legal shortcut characters are letters from the English alphabet (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, and Z, either uppercase or lowercase) and single decimal digit characters (0, 1, 2, 3, 4, 5, 6, 7, 8, and 9). If the character following the last '&' is not a legal shortcut character, then SuiteFactory will still display that character with an underline, but typing the underlined character will have no effect. (See examples in Table 1.)

Table 1: Shortcut character examples

About Substitution Parameters

Sometimes SuiteFactory must display data that it calculates or looks up while the program is running. Text that contains this kind of information must include place-holders where SuiteFactory can insert the data. These place-holders are called "substitution parameters".

CAD/CAM Integration defines whether a string resource should contain substitution parameters and what data replaces each one. Substitution parameters are represented as:

$(n)

where "n" is the id number of the parameter.

If a string resource has a list of parameters, you should make sure that your translation includes each parameter at least one time. Parameters may appear in any order in your translation, and they may appear as many times as the translation requires.

For example, a string resource may need to display the name and the version of a DNC File. The resource's parameter list includes "DNC File Name" as parameter 1 and "DNC File Version" as parameter #2. Possible strings could include:

·         "Editing DNC File '$(1)' version $(2)"

·         "Are you sure you want to delete version $(2) of DNC File $(1)?"

Figures

Figure 1: Manage String Resources window

Figure 2: Translate string window example 1

Figure 3: Translate string window example 2