Compile Mono Resource Text Files with resgen

Mono applications keep their strings in .resources files, and resgen is the tool that turns your plain key=value text into that binary format. Allow about ten minutes.

The commands below use the installed Mono Resource Generator 6.8.0.105 from package mono-devel. You need a shell, Mono's development tools and a writable temporary directory. This guide changes only files below a new directory in /tmp, needs no elevated privileges, and sudo should not appear in any of the examples.

1. Check the installed tool

Confirm which executable the shell will run and record its version:

$ command -v resgen
/usr/bin/resgen
$ resgen --version
Mono Resource Generator version 6.8.0.105

There is also a resgen2 executable on this installation. The manpage describes resgen2 as the variant with the -usesourcepath option, but the installed resgen help lists that option too, as /useSourcePath. Use whichever version is present on the machine where your build actually runs: do not assume another Mono release accepts exactly the same spelling.

2. Create a small text resource

Make a unique temporary workspace and write a resource file. A line beginning with # or ; is a comment. Resource values can contain escaped newline, carriage-return, tab and backslash characters.

work=$(mktemp -d /tmp/resgen.XXXXXX)
printf '%s\n' \
  '# labels used by the example' \
  'welcome=Hello, Ada!' \
  'shortcut=Save\\tCtrl+S' \
  'two_lines=first\\nsecond' > "$work/messages.txt"
sed -n '1,10p' "$work/messages.txt"

Keep the source as plain text while you edit it. Keys are the names your application will request later, so changing a key is an application change, not just a formatting one.

Expected source:

# labels used by the example
welcome=Hello, Ada!
shortcut=Save\\tCtrl+S
two_lines=first\\nsecond

3. Convert one file explicitly

Pass the source followed by the destination. An explicit destination stops a build script from silently writing beside an input file when that is not what you intended.

resgen "$work/messages.txt" "$work/messages.resources"
file "$work/messages.resources"

On this Mono version the conversion reports the resources it read and ends with Writing resource file... Done.. The file command identifies the result as data rather than ordinary text: it is the binary format read by .NET's resource reader, so never edit .resources in a text editor.

If you omit the destination, resgen uses source.resources; for example, resgen "$work/messages.txt" creates messages.resources in the same directory. That default suits a one-off conversion, but an explicit destination is easier to audit in build logs.

4. Read the result back as a check

Conversion success is not the same as checking the contents you meant to publish. Convert the binary result back to text and inspect it:

resgen "$work/messages.resources" "$work/roundtrip.txt"
sed -n '1,10p' "$work/roundtrip.txt"

You should see the three keys, with the escaped values preserved. The order may differ from the source because the resource file is a key-value store, so compare keys and values rather than relying on line order:

tabbed=left\\tCtrl+S
welcome=Hello, Ada!
two_lines=first\\nsecond

5. Batch-compile several files

Use /compile before the resource specifications. Each item can be just a source path, which changes its extension to .resources, or a comma-separated source and destination pair.

printf '%s\n' 'menu.file=File' > "$work/english.txt"
printf '%s\n' 'menu.file=Fichier' > "$work/french.txt"
resgen /compile \
  "$work/english.txt,$work/english.resources" \
  "$work/french.txt"
file "$work/english.resources" "$work/french.resources"

The command creates both binary files. The explicit pair fixes the English output name; the French item uses the documented extension replacement and creates french.resources beside its source.

Common traps

• Putting /compile after a source path. The command line can fail outright because the switch must come first.
• Pointing an example at a live resource file. If a destination already exists, treat replacement as a build decision: check the path first, and only proceed with a backup or the ability to regenerate it.

6. Use conditional text only on a known Mono version

The installed 6.8.0.105 help documents /define:SYMBOL1,SYMBOL2 for conditional inclusion in .txt files. This option is not shown in the older local manpage, so keep it tied to a tested Mono version:

printf '%s\n' \
  '#ifdef FEATURE' \
  'new_label=Enabled' \
  '#endif' \
  '#if ! OMIT' \
  'fallback=Included' \
  '#endif' > "$work/conditional.txt"
resgen /define:FEATURE "$work/conditional.txt" "$work/conditional.resources"
resgen "$work/conditional.resources" "$work/conditional-roundtrip.txt"
sed -n '1,10p' "$work/conditional-roundtrip.txt"

The round-trip output contains new_label=Enabled because FEATURE was defined, and fallback=Included because OMIT was not. If another machine rejects this option, remove the conditional directives or use the exact resource-generation version that supports it.

7. Handle failures without guessing

• Unknown extension or malformed input: read the diagnostic and inspect the source. The documented formats are text, .resources, .resx and .po; a file extension alone does not make its contents valid.
• File unexpectedly overwritten: stop the build, restore it from version control or a backup, and fix the destination argument. There is no undo operation in resgen.
• Missing assembly during a .resx conversion: the manpage says resgen loads referenced assemblies from Mono's assembly cache, so repair the dependency or run the conversion in the build environment that contains it.

The temporary workspace is safe to leave for inspection. Remove it only after you have finished checking the output, verify the path before deleting anything, and never substitute a broad directory for "$work".