.RESX File Format – Localisation and the build

.NET resource file

Cultures

One .resx per culture. The neutral file is Strings.resx; a culture’s file adds the culture name before the extension: Strings.fr.resx (French), Strings.fr-CA.resx (French in Canada), Strings.zh-Hans.resx. Each file need hold only the names that differ; a lookup that finds nothing in fr-CA tries fr, then the neutral file (the fallback chain). Files with the same names as the neutral file and the extra ar-JO, ru and other suffixes are found in real projects, as the files tested for this page show.

The build

  1. An MSBuild item EmbeddedResource names the file (in SDK-style projects every .resx is one by default). The GenerateResource task runs resgen-style code over it and writes a binary .resources file, Namespace.Strings.resources, named from the project’s root namespace and the file’s path.
  2. The .resources file is embedded in the assembly. The neutral file goes into the main assembly; each culture’s file goes into a satellite assembly Name.resources.dll in a folder named by the culture (fr/), built by the Assembly Linker.
  3. For a file marked Generator = ResXFileCodeGenerator (or PublicResXFileCodeGenerator) Visual Studio writes a designer file Strings.Designer.cs: a class with a static property for each name (Strings.Greeting) that calls ResourceManager.GetString or GetObject. The class is made by StronglyTypedResourceBuilder, and the names must be valid identifiers (others are changed).
  4. At run time a ResourceManager opens the .resources of the current UI culture (CurrentUICulture), falls back along the chain, and returns the value.

A Windows Forms form’s Form1.resx is read by InitializeComponent through ComponentResourceManager.ApplyResources: each name control.Property sets that property of that control, so a translated .resx re-lays out the form without code (Localizable = True on the form).

RESW (UWP and WinUI)

The same XML shape, one folder per language tag instead of a suffix: Strings/en-US/Resources.resw, Strings/fr-FR/Resources.resw. A name is Uid.Property: with <Button x:Uid="Save"/> in XAML, the entry Save.Content sets the button’s Content, and Save.AutomationProperties.Name sets an attached property (the name after the first dot is the property path). A name with no dot, or with a / (Dialogs/Title), is a string loaded in code by ResourceLoader.GetString. A .resw file holds strings only: data entries with a name and a value, and the same four resheaders. The build turns the files into a PRI file (resources.pri) that the app’s resource manager reads.

The binary .resources file

A .resources file is a header (a magic number, the reader and resource set type names), a table of names and offsets, and the values in a data section; it is read by ResourceReader. It is not text and has no separate page here; its use is to be embedded in assemblies.

Not described

Known, not yet covered

  • Reference: the byte layout of .resources files and of PRI files is not described.
  • Reference: the exact naming rules the build uses to turn a path into the resource name (Namespace.Folder.Name.resources, DependentUpon, LogicalName) are summarised only.

Unknown

  • Reference: the build was not run here (no .NET SDK is installed); the steps are from Microsoft’s documentation.