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.SelectedPathis keyed by the full control type,System.Windows.Forms.FolderBrowserDialog. That type comes from>>control.Typein the.resxand from the designer file. On .NET the designer file often uses a short name, such asButton, and the.resxdoes 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, andZOrderin the.resx. Binary localization rebuilds the same layout from the compiledInitializeComponentmethod. When that fails, the form is shown incorrectly. -
Translator comments survive. A
.resxitem 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.resxagain. -
Resource strings appear on the form that uses them. Soluling can scan the C# or Visual Basic source, find where a string from
Resources.resxis used, and show that row on the form node. -
Localizableis checked. WithLocalizableleft atfalse, Visual Studio writes the properties intoInitializeComponentand the.resxhas almost nothing to translate. Project localization sees that from the.resxand 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 asForm1.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
.exenext to the application is an unmanaged host. The forms are in the.dll. The project file points at that assembly. Selecting the.exefor 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
- Windows Forms guide - step 02, create the Soluling project
- WPF guide - step 02, create the Soluling project
- Windows Forms localization - the full Desktop documentation
- WPF localization - the full Desktop documentation
- .NET localization - resource files, satellite assemblies, and the three localization methods