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.
The properties for the RC Filter are the following:
The following resources are not extracted (they are left untouched when processing the file):
DLGINITresource other than the ones of type 0x403 and 0x1234.
BITMAP refer to the resource
ICON and resource
not icon and bitmap controls in a dialog box, those are treated like any other
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.
#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
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.
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.
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.
With this filter, because in dialog boxes comments after a controls are associated with that control, you cannot use grouped directives (e.g.
_eskip) the ending directive would be applied one control to
early. Therefore, inside dialog box declaration you should only use single directives (e.g.
at the front of each control.
The constructs modified by the filter are the following:
#pragma code_pageif the merged text is in a different encoding.
DLGINITextracted entries may be reformatted differently.
The constructs that may need to be modified manually:
defined(AFX_TARG_XXX)where XXX is the MFC language code of the resource.
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.
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:
This matches the C-style
printf variables (e.g. "
%1$d", etc.) and the escaped sequences:
\t", and "
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.
In order to maximize the capabilities of localization tools you may want to consider implementing the following good coding practices in your resources: