Okapi Components

Overview

The NETRes Filter is an Okapi component that implements the Okapi Filter Interface for .NET 2.0 Resource files.

Currently the filter supports ResX files and compiled .resources files, not compiled Assembly files. The filter also does not support ResXDataNodes objects. Only files for .NET 2.0 are supported (this is due to incompatibility in the resource reader of the .NET Framework itself). You may be able to process simple ResX files for .NET 1.0 and 1.1 using the XML Filter. Otherwise to process .NET 1.1 files, use the filter version 1.0.6 shipped with Rainbow version 5.0.6 (Release 8). Note also that the .NET Text Properties files (any version) are supported with the Properties Filter.

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

<?xml version="1.0" encoding="utf-8"?>
<root>
...
 <data name="FILTER_NAME">
  <value>Okapi Properties Filter</value>
  <comment>Caption of options dialog box</comment>
 </data>
 <data name="VAR_DESCRIPTION">
  <value>Properties Files</value>
 </data>
 <data name="CANTOPENFILE">
  <value>Cannot open the file '{0}'.</value>
 </data>
</root>

Not all <value> elements are translatable: When the ResX file describes a form for example, most entries are non-translatable properties of controls.

Note also that some entries (such as the text items in the TreeView or the ListView controls) are not in plain text, but in binary form, even in ResX format.

Filter Properties

The properties for the NETRes Filter are the following:

Processing Details

Output Order

For ResX documents, the output list of <data> elements is generated in an order that may be different from the order in the original document. This has no effect in the validity of the resources, but may prevent you to do meaningful comparisons between the original document and the output.

You may use the Text Rewriting utility with the option Keep the original content to generate a file that could be used for comparison.

Input Encoding

The input encoding is automatically detected. The user parameter passed to the filter is ignored.

Output Encoding

The output encoding is always either UTF-8 or UTF-16 depending on the type of resource. The user parameter passed to the filter is ignored.

Localization Directives

Localization directives can be used in ResX files only, not to .resources files.

Comments can be included in ResX files, using the <comment> element. Note that the position of the <comment> element before or after the <value> element is ignore: the directives in a comment applies to the current <data> entry.

For example, in the following example, only the bolded text will be extracted:

...
<data name="FILTER_NAME">
 <value>Okapi Properties Filter</value>
 <comment>_skip</comment>
</data>
<data name="VAR_DESCRIPTION">
 <value>Properties Files</value>
</data>
<data name="CANTOPENFILE">
 <value>Cannot open the file '{0}'.</value>
/data>
...

Note: XML comments (<!--...-->) are ignored.

VERY IMPORTANT:
While block directives (_bskip/_eskip and _btext/_etext) are supported, it is NOT A GOOD IDEA to use them with ResX files as the order of the entries is re-arranged in the output file, and therefore the block markers may end up completely mixed up in the output.

Line-Breaks

The line-breaks type of the output are the same as the one of the original input.

Ancillary Files

ResX and .resources files may contain graphic objects such as bitmaps, or icons. The filter can extract these objects as separate ancillary files using the GenerateAncillaryData method.

Item Properties

This filter implement support for one item property:

Potential Issues

The filter uses the built-in ResxResourceReader class of the .NET Framework and does not have complete control on how the files are parsed. There are a few issues for the parser:

a) Some ResX or Resources files generate a "Invalid ResX input" error at the beginning of the parsing because the file contains version information conflicting with the version information of the reader. This is documented by Microsoft (http://support.microsoft.com/default.aspx?scid=kb;en-us;Q316196). You may or may not be able to resolve the problem by re-generating the ResX files using ReGenResx.exe, a utility provided by Microsoft.

b) Some ResX or Resources files may generate errors if they contain objects referring to a library which you do not have, or which is not located in the .NET GAC (Global Assembly Cache).

c) The ResXResourceReader class has problem reading the resources of type System.Resources.ResXFileRef that have a relative path. You may get the error "ResX file Could not find a part of the path '<PathName>'". One way to resolve the issue is to use a full path for the reference. For example change:

<data name="MnuPreviousFile" type="System.Resources.ResXFileRef, System.Windows.Forms">
 <value>Properties\MnuPreviousFile.bmp;System.Drawing.Bitmap, System.Drawing,
  Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a</value>
</data>

To this:

<data name="MnuPreviousFile" type="System.Resources.ResXFileRef, System.Windows.Forms">
 <value>C:\MyProject\Properties\MnuPreviousFile.bmp;System.Drawing.Bitmap, System.Drawing,
  Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a</value>
</data>

This is not a very good solution since you will have to change the full path if you move the project to another folder (which is very likely to happen during localization). Another workaround is to embed the resources directly into the ResX file rather than reference them.

Alternative Solution to Parse ResX Files

If you cannot process a ResX file with the NETRes Filter, you may be able to process it with the XML Filter. However, because ResX files are complex and hold many types of data that are not text, this is only a very limited solution. Most likely, using the XML Filter on ResX files will extract more data than you want, and some text cannot not get extracted because it resides inside binary strings (e.g. list box content).

The following is an example of XLP/ITS file to use to process ResX data.

<its:rules xmlns:its="http://www.w3.org/2005/11/its" version="1.0"
 xmlns:xlink="http://www.w3.org/1999/xlink"
 xmlns:itsext="okapi-framework:its-extensions">
 <its:translateRule selector="/root" translate="no" />
 <its:translateRule selector="//data[not(@mimetype)]/value" translate="yes"
  itsext:idRef="../@name" itsext:whiteSpaces="preserve" />
</its:rules>

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. Note that localization directives applies to ResX files only, not to .resources files.

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.

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])
|((\\r\\n)|\\a|\\b|\\f|\\n|\\r|\\t|\\v)
|(\{\d.*?\}))

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

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.