.NET

Project and binary localization

When you have the Visual Studio project, add the .csproj. That is the better source for a Windows Forms or WPF application. Both methods write the same deployable result: one satellite assembly per language, such as de\YourApp.resources.dll, next to the original assembly.

The difference is what Soluling can see while it scans and while you edit. This page is the detail behind step 02 of the Windows Forms and WPF guides.

On this page

What each method reads

Project (<code>.csproj</code>) Binary (<code>.exe</code> / <code>.dll</code>)
Input The project file. Soluling finds every .resx, form, XAML file, and image from it. A .sln does the same for every project in the solution. The compiled assembly only.
Windows Forms The original .resx, including the design-time entries and the .Designer.cs or .Designer.vb file. The compiled .resources data inside the assembly.
WPF The original .xaml and .resx files. The compiled XAML (BAML) and the compiled resources.
Output Satellite assemblies. Build the project in Visual Studio first: Soluling's build uses the assembly name, version, and signing. Satellite assemblies by default. It can also write a localized copy of the assembly itself.
Source code Required. The assembly is enough.

A Windows Forms .resx stores more than the values the application reads at runtime. The designer writes entries whose names start with >>, such as >>button1.Type, >>button1.Parent, and >>button1.ZOrder, and a <metadata> block that includes Localizable. Comments sit on the resource items. The compiler leaves those names and that metadata out of the .resources blob. A compiled form keeps the runtime property values and their CLR types: the text, the size, the position.

Benefits of project localization

  • Scan rules match the real control. A rule that skips FolderBrowserDialog.SelectedPath is keyed by the full control type, System.Windows.Forms.FolderBrowserDialog. That type comes from >>control.Type in the .resx and from the designer file. On .NET the designer file often uses a short name, such as Button, and the .resx does not list a type for every control, so Soluling reads the designer file and keeps the full name from the .resx. Those >> entries are absent from the compiled assembly, so a type-specific rule has nothing to match.
  • The visual form editor follows the designer. The editor builds the form from Type, Parent, and ZOrder in the .resx. Binary localization rebuilds the same layout from the compiled InitializeComponent method. When that fails, the form is shown incorrectly.
  • Translator comments survive. A .resx item can carry a <comment>, and project localization reads it. A compiled resource has the name and the value. Binary localization can recover the comments only by finding the original .resx again.
  • Resource strings appear on the form that uses them. Soluling can scan the C# or Visual Basic source, find where a string from Resources.resx is used, and show that row on the form node.
  • Localizable is checked. With Localizable left at false, Visual Studio writes the properties into InitializeComponent and the .resx has almost nothing to translate. Project localization sees that from the .resx and the designer file, warns, and can skip writing a localized resource for that form.
  • New files show up on the next scan. One .csproj, or the .sln, covers every form and .resx. A form you add later appears the next time you scan. Existing localized files, such as Form1.fi.resx, are imported. Soluling uses a satellite assembly for a language only when that language has no localized .resx.
  • A scan reads the file you just edited. Strings come from the .resx, so a scan reflects the form as it is in Visual Studio. Building the satellite still needs the compiled assembly.
  • On .NET 5 and later, you localize the assembly that contains the forms. The .exe next to the application is an unmanaged host. The forms are in the .dll. The project file points at that assembly. Selecting the .exe for binary localization localizes the host, which has no forms.

WPF

WPF uses the same two methods, and the same reasons favor the project: comments, resource-string locations, and new files found on the next scan. The form-specific difference is the XAML.

Project localization reads the .xaml files. An element can be identified by x:Uid, Uid, x:Name, Name, x:Key, or AutomationProperties.AutomationId. Binary localization reads BAML, the compiled XAML inside the assembly. BAML cannot be turned back into the original XAML, so localization goes through the .NET localization API and is more limited. An element without an x:Uid cannot be localized from the assembly. Add the attributes with MsBuild /t:updateuid Driving.csproj before you build, if you localize the assembly.

When the assembly is the right source

Use the compiled assembly in these cases:

  • You have the build and no project. Soluling reads the assembly and writes the satellite assemblies from it.
  • You want one file per language. Binary localization can write a localized copy of the assembly: the same code, with the resources translated. You deploy that file in place of the original.
  • Strings are hard-coded in the IL. Soluling can localize those strings only from the assembly. Doing that turns satellite output off, and you have to exclude every string that must stay as it is, such as SQL.

On .NET 5 and later, add the main .dll. The .exe with the same name is the native host.

Related

All guides