Sisulizer supports three different methods to localize .NET applications. The methods are:
Each method has it advantages and disadvantages. You must choose the method that best suits your needs.
In addition of localization methods this topic contains information about the following issues:
When using the assembly localization user selects an assembly file (.exe or .dll) to be localized. Sisulizer scans all the resource data from the application including XAML, form, string, icons, image and version data. On the build process Sisulizer creates the localized satellite assembly files containing localized resources.
If you localize VCL.NET applications you must use assembly localization.
When using the project localization user selects a project file (.csproj, vbproj, .bdsproj) or solution file (.sln) of the application to be localized. Sisulizer reads the project file(s) to find out the resource files (.xaml, .resx or .txt) that need to be localized. On the build process Sisulizer creates the localized resource files. Sisulizer can automatically compile the created localized resource files into compiled resource files (.baml or .resources) and finally link the compiled resource files to satellite assembly files (.dll).
Sisulizer supports C#, Visual Basic and Delphi projects. Project file localization can be used if you have the full source code available and you use either Microsoft Visual Studio or Borland/CodeGear Developer Studio.
When using the resource file localization user selects a resource file (.xaml, .resx or .txt) to be localized. On the build process Sisulizer creates the localized resource files. Sisulizer can automatically compile the created localized resource files to compiled resource files (.resources).
Resource file localization can be used if you have the original resource files (.xaml, .resx or .txt).
The following table compares different localization methods.
| Feature | Assembly | Project | Resource |
|---|---|---|---|
| No .NET SDK or runtime need to be installed | yes | yes | yes |
| Gets full menu structure information | yes | yes | - |
| Sisulizer can run localized applications | yes | yes | yes (.xaml only) |
| Creating signed satellite assembly files | yes | yes | - |
| No source codes needed | yes | - | - |
| Compatible to VCL applications | yes | - | - |
Our recommendation is to use either the project file or assembly file localization.
.NET assemblies contains two kind of resources: managed and unmanaged. Unmanaged are the standard WIN32 resources. .NET applications usually use only icon and version typed WIN32 resources. Managed resources are the resource data that is linked inside the assembly as a managed resource data. Most .NET applications use only one type of managed resource: .resources files. They can contain form data, string data, images, etc. In addition of that it is possible to add any file as a resource to an assembly file. Some applications add XML, HTML or image data such way. Sisulizer can visually localize .resources, XML, HTML or image data. In addition of that any custom file that have been added as a resource can be localized as binary value.
Sisulizer can localize all kind of resource data of .NET assembly files. The following table tells how each resource type is handled.
| Resource | Type | Description |
|---|---|---|
| .resources | managed | These contain either form data or resource table that contains text, images, etc. Original these files are in .resx or .txt format but .NET compiler compiles them into binary .resources format before embedding them to the assembly file. |
| XML | managed | These contain data of embedded XML files. |
| HTML | managed | These contain data of embedded HTML files. |
| Image | managed | These contain data of embedded image files. |
| Binary | managed | These contain data of all other embedded files. |
| Icon | unmanaged | This contain the icon of the application. |
| Version | unmanaged | This contain the version data of the application. |
In order to localize applications using Windows Forms you have to turn true the Localizable property of all forms and user controls.
Read more about Localizable property.
Generally Sisulizer does not need .NET runtime or SDK. However on certain situations one or both are needed.
When Sisulizer creates localized satellite assembly files for a .NET project or assembly it need to use .NET runtime tools. Without .NET runtime Sisulizer can not create localized satellite assembly files. If you do not have .NET runtime installed you can download it from Microsoft's site.
In order to completely scan .NET assembly files (.exe or .dll) and to compile localized resource files (.resx) Sisulizer needs to know the location of the .NET SDK (e.g. C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0).
SDK directory is optional. If no value is given Sisulizer does not compile localized resource files and satellite assembly files when localizing .NET project files (e.g. csproj), and Sisulizer does not extract complete menu and container hierarchies when localizing .NET assembly files. We strongly recommend to install .NET SDK to make it possible for Sisulizer to use the SDK tools. SDK is installed with Microsoft Visual Studio or Borland Developer Studio. If you do not have .NET SDK you can download it from Microsoft's site.
Choose the Version sheet of Tools | Platforms | .NET dialog to configure SDK directories.
When you create a new Sisulizer project for your .NET project Sisulizer can automatically import existing translations. If you disabled importing during the project creating you can import the existing translations later by using the following instructions.
If your have signed your assembly file Sisulizer will automatically sign the satellite assembly files it creates. However this automatic signing work only if you use project file localization. If you use assembly file localization you have to make Sisulizer to sign satellite assembly files. To do that add key file parameter to the assembly linker parameter list.
You can either write the text directly or you can right click on the edit field and choose Add key file item from the menu.
WPF library contains some predefined commands. They are defined in ApplicationCommands class. These command contain some user interface strings such as command's label. These are the strings to be show in the menu items. If you use command's of ApplicationCommands the strings won't stored anywhere in your project or assembly file but are stored in the frameworks assembly files. This is why the strings do not appear to Sisulizer project either.
The best way to localize the menus and toolbars using these commands is to add the header attribute to the item. This makes framework to use the text of in the attribute instead of the default string in the command. The string will also appear to Sisulizer project so it can be localized. For example if you have following XAML line:
<MenuItem x:Uid="newMenu" Command="ApplicationCommands.New"/>
Add Header attribute into it:
<MenuItem x:Uid="newMenu" Header="_New" Command="ApplicationCommands.New"/>
After this the menu item can be localized.
When Sisulizer scans XAML data (either .xaml file or BAML resource inside assembly file) it needs a context information for each component. To get this context information Sisulizer looks for special name/context attributes that contain the name of the control. There are three possible attributes: x:Uid, x:Name and Name. If your XAML data does not contain name attributes Sisulizer will write the following hint to the log file:
21:02:46 Hint fileName.MenuItem[2] component has no name. It is recommended to give a name using either Name, x:Name or x:Uid attribute.
To give a property content information for a component add one of the above context attributes and give a unique value to it. You can automate this process by using MsBuild tool. Use the following command line:
msbuild /t:updateuid myproject.csproj
MsBuild tool can be found from .NET framework directory (e.g. C:\Windows\Microsoft.NET\Framework\v3.5\MsBuild.exe)
WPF resource file, XAML files (.xaml), do not contain type information of the properties or does not even contain information if the element is property of event. This sets some difficulties for localizations. Without type information Sisulizer can not figure out if data is property or event and if property what is the type. In general you want to scan most string data but only certain integer data (e.g. Left, Top). Scanning of integer data is hard coded to Sisulizer and it can property scan layout of all component including 3rd party components. The problem appears when scanning a 3rd party control that is not know by Sisulizer. Without type information Sisulizer can not figure out what custom properties are string typed and what are not. This is why it can just not scan all unknown properties. That would make it to scan all other data type and events too. For all other modern resources types such as VCL's .dfm or WinForms's .resx contain type information. For these platforms Sisulizer can safely scan all string properties without getting huge amount of unnecessary rows. If you want to exclude scanning of a property you can easily exclude it. This same approach does not work for XAML because Sisulizer would scan basically all data including events names. This is why in WPF Sisulizer only scan the known properties such as Text, Left, Top, Background, etc. Sisulizer team has tested all standard WPF controls and all properties of them that are needed to be scanned are scanned. If you use 3rd party WPF controls you have to add the "custom properties" to the included property list in the component mapping.
Sisulizer's NET directory contains Windows Forms samples and WPF directory contains WPF samples.