Okapi Components

Overview

The RC Filter is an Okapi component that implements the Okapi Filter Interface for Windows RC resource files.

The following is an example of a very simple RC file. The translatable text is marked in bold underlined.

#include "resource.h"
LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US
#pragma code_page(1252)

IDD_GETFILES DIALOGEX 0, 0, 304, 90
STYLE DS_SETFONT | DS_MODALFRAME | DS_FIXEDSYS | WS_POPUP |
 WS_CAPTION | WS_SYSMENU
CAPTION "Load Files"
FONT 8, "MS Shell Dlg", 400, 0, 0x1
BEGIN
   GROUPBOX "",IDC_GRPMASK,4,2,296,66,WS_GROUP
   EDITTEXT IDC_MASK,10,12,264,13,ES_AUTOHSCROLL
   PUSHBUTTON "...",IDC_GETMASK,278,12,15,13
   CONTROL "Include files in &sub-folders",IDC_RECURSIVE,"Button",
      BS_AUTOCHECKBOX | WS_TABSTOP,10,28,134,10
   LTEXT "To specify several masks, simply separate them with a semi-colon.",
      IDC_NOTE,12,42,280,20
   DEFPUSHBUTTON "OK",IDOK,142,72,50,14,WS_GROUP
   PUSHBUTTON "Cancel",IDCANCEL,196,72,50,14
   PUSHBUTTON "Help",IDC_SHOWHELP,250,72,50,14
END

The filter provides access to more than the translatable text. For example, coordinates, resource types, and IDs, are also extracted and modifiable when appropriate.

Filter Properties

The properties for the RC Filter are the following:

Processing Details

Limitations

The following resources are not extracted (they are left untouched when processing the file):

• ACCELERATORS
• HTML
• ICON
• BITMAP
• RCDATA
• VERSIONINFO
• Any user-defined resource
• Any entry in DLGINIT resource other than the ones of type 0x403 and 0x1234.

Note that ICON and BITMAP refer to the resource ICON and resource BITMAP, not icon and bitmap controls in a dialog box, those are treated like any other controls.

Comments in one of the Pascal language style (i.e. "(*...*)") are not supported directly. Most of the time, this does not affect the correct parsing of the file, but it means that localization directives used inside this type of comments are not recognized.

Encodings

The #pragma code_page statement are supported.

An RC input file may have different parts encoded in different encodings. The filter switches from one encoding to the next as the #pragma code_page are processed. Note that using such RC files is not recommended, nor is using multilingual RC files: it simply makes the localization more complicated.

DLGINIT Entries

The DLGINIT entries are supported if they are of type 0x403 or 0x1234. However, when output in a none-native format (e.g. with an RTF layer) you may need to make modification to the code to load the file properly in a resource editor.

The format of these entries includes a parameter that indicates the number of bytes of the text item. If you make a change in the text and either increase or reduce its length, you must update the length parameter. The length parameter is located just after the type indicator (e.g. 0x403 or 0x1234) and must equal the length in bytes of the text + 1 (for the trailing zero).

For example, before translation:

IDD_WINRCTEST_DIALOG DLGINIT
BEGIN
    IDC_COMBO1, 0x403, 7, 0
"Line 1" ,"\000"
    IDC_COMBO1, 0x403, 7, 0
"Line 2" ,"\000"
    IDC_COMBO1, 0x403, 4, 0
"123" ,"\000"
    IDC_COMBO1, 0x403, 9, 0
"à=agrave" ,"\000"
0
END

After translation and update of the length parameter:

IDD_WINRCTEST_DIALOG DLGINIT
BEGIN
    IDC_COMBO1, 0x403, 8, 0
"Ligne 1" ,"\000"
    IDC_COMBO1, 0x403, 8, 0
"Ligne 2" ,"\000"
    IDC_COMBO1, 0x403, 4, 0
"123" ,"\000"
    IDC_COMBO1, 0x403, 17, 0
"à=a accent grave" ,"\000"
0
END

Note that when a DLGINIT string is modified manually (for example, when translating in a RTF output), the byte-length value may have to be be updated manually to match the new length of the translated string.

Localization Directives

The filter supports localization directives. They are special comments you can use to override the default behavior of the filter regarding the parts to extract.

The syntax and behavior of the directives are the same across all Okapi filters. See the Localization Directives pages for detail information about what you can do with the mechanism.

Note

With this filter, because in dialog boxes comments after a controls are associated with that control, you cannot use grouped directives (e.g. _bskip ... _eskip) the ending directive would be applied one control to early. Therefore, inside dialog box declaration you should only use single directives (e.g. _skip) at the front of each control.

Output Modifications

The constructs modified by the filter are the following:

• Text of extracted items.
• Value of the #pragma code_page if the merged text is in a different encoding.
• Values for the LANGUAGE statement.
• Spliced strings are merged as un-spliced.
• DLGINIT extracted entries may be reformatted differently.

The constructs that may need to be modified manually:

• The defined(AFX_TARG_XXX) where XXX is the MFC language code of the resource.

Parameters - Options Tab

Use localization directives when they are present -- Set this option to enable the filter to recognize localization directives. If this option is not set, any localization directive in the input file will be ignored.

Extract items outside the scope of localization directives -- Set this option to extract any translatable item that is not within the scope of a localization directive. Selecting to extract or not outside localization directives allows you to mark up fewer parts of the source document. This option is enabled only when the Use localization directives when they are present option is set.

See the Localization Directives section for more details on how the filter deals with directives.

Use Do-Not-Localize list if a DNL file is present -- Set this option to enable the filter to utilize any Do-Not-Localize list file found along with a given input file. The DNL file has the path and name as the input file, with an additional .dnl extension. It contains a list of entries that should not be extracted. Each entry is made of the resname, restype and text of a filter item. Use the DNL List Editing utility to create and maintained DNL files.

Parameters - Inline Codes Tab

Mark as inline codes the text parts matching this regular expression -- Set this option to use the specified regular expression to be use against the text of the extracted items. Any match will be converted to an inline code. By default the expression is:

((%(([-0+#]?)[-0+#]?)((\d\$)?)(([\d\*]*)(\.[\d\*]*)?)[dioxXucsfeEgGpn])
|(\\a|\\b|\\f|\\n|\\r|\\t|\\v))

This matches the C-style printf variables (e.g. "%s", "%2.3f", "%04X", "%1$d", etc.) and the escaped sequences: "\r\n", "\a", "\b", "\f", "\n", "\r", "\t", and "\v".

Edit Expression -- Click this button to edit the regular expression and its options.

See the Regular Expressions section for more information about the syntax and rules for building regular matching patterns.

Good Coding Practices

In order to maximize the capabilities of localization tools you may want to consider implementing the following good coding practices in your resources:

• Use unique IDs whenever possible. For example, replace the often-used default IDC_STATIC identifier by unique IDs. This will reduce the number of cases where tools have to deal with different entries with no ID difference, and make tasks like alignment, update, etc. easier and safer.
• Do not modify IDs. Once an item has an ID, restrain yourselves to change that ID. This will help in reducing the number of "new" items that are simply "renamed" items.
• Use external files for HTML resources. Avoid embedding HTML files within the RC file. They are treated separately by localization tools, make the handling much easier by separating them from the resources.
• Use different files to store different languages. You can have several languages within the same RC file, but this practice can be extremely counter-productive during localization. There is nothing wrong with grouping different languages in the same compiled file, but do this at compile time.