Chapter 10

SECTION 5: CUSTOMISING LAUNCHER MESSAGES

Snug includes English launcher messages, so customisation is optional. Start with the short tutorial below to change and preview one message. The dialog guide explains where messages appear; the Message Key Reference and complete token tables are provided for reference.

Your First Message Change and Preview

First, generate a starter localisation file in PowerShell:

`Command(s)`
`.\snug.exe --init-localisations`

Open localisations\snug-localisations.en.txt in a plain-text editor. Find runtime.prompt.heading and change only its value to:

runtime.prompt.heading = Install Java to start this application

Keep the key exactly as written, then save the file. This heading does not accept replacement tokens.

Next, open Snug Preview to see how your edited message appears. This is a separate program that displays launcher dialogs without requiring a complete application rebuild.

To open the preview, run:

`Command(s)`
`.\snug_preview.exe --localisation ".\localisations"`

Select English (en), then open the runtime installation confirmation dialog. Check that its main heading reads “Install Java to start this application”.

Image: The running Snug Preview, which allows you to select the dialog that you wish to preview.

The screenshot uses an optional application icon. To preview your own branding, use the --icon option described under Previewing Your Changes.

`Command(s)`
`.\snug_preview.exe --localisation .\test\localisations\ --icon .\test\test-icon.png`

This example uses the Snug project's test files; replace these paths with your localisation directory and icon.

Understanding Launcher Dialogs

Most launches are uneventful: the person using your application double-clicks its executable, and the Java application starts. When Snug needs to communicate, its dialogs fall into two main groups.

Runtime Installation Dialogs

These dialogs appear when Snug needs to obtain a compatible Java runtime. Snug first asks the user to confirm installation. If the user agrees, a progress window shows the download, verification, and extraction stages.

If installation encounters a problem, Snug may display a retry or failure dialog.

Cannot Launch Dialogs

The Snug launch-error window uses launcher.error.* keys for its wording and the relevant err.* key for the underlying error. Built-in English is available when custom localisation is unavailable. Windows failures before the Snug launcher has initialised are separate: these localisation keys do not control Windows' own messages.

Image: The Cannot Launch dialog appears when the Snug-packaged application cannot be launched.

Customising the Messages

You can leave the default English messages alone, replace their wording with language that suits your application, or supply translations. The messages are stored as named entries in a localisation file. Each entry has a key that Snug recognises and a value containing the wording shown to the user. Some values also contain replacement tokens, such as {version}, which Snug fills in when the dialog appears.

For example, the structure of a message entry is:

runtime.progress.pct_label = {pct}%

Here, runtime.progress.pct_label is the message key, and {pct} is a replacement token. Snug supplies the current percentage when showing the progress dialog. When editing a localisation file, leave both the key and supported replacement tokens intact. Change the surrounding words to suit the people using your application. This is a teaching example of a custom value, not a quotation of Snug's default English wording.

A Simple Editing Workflow

Start with a copy of a Snug localisation file for the language you want to customise. Keep the original keys unchanged.
Open the copy in a plain-text editor and change the values for the messages you want to personalise. You do not need to rewrite every message.
Save the file, then use snug_preview.exe to inspect the changed wording and buttons.
Add the localisation file or directory to snug.options, build your executable, and check the result.

IMPORTANT: If a translation is missing a message, Snug uses the available fallback wording for that message, ultimately falling back to built-in English. Other translated messages remain available.

For example, to use a directory of language files, include an option like this in snug.options:

--localisation "snug\localisation"

Section 4: Configuration Options gives the accepted values and full option reference.

Image: Edit the text after the equals sign, not the key.

Which Messages Can I Change?

The messages cover runtime installation and errors that prevent an application from launching. You can customise the wording of headings, explanations, and supported button labels. Changing a message does not change what a button does or how Snug handles an error.

IMPORTANT: Localisation changes the wording of Snug's dialogs, including supported button labels. It does not change button actions or error handling.

Use the following dialog guide to identify the message you want to change. For exact key names and token support, use the reference tables later in this section.

Understanding Dialog Layouts

Most Snug runtime dialogs share a common layout. Rather than learning a completely different set of localisation keys for every window, you can recognise the same parts by their key suffixes. The dialog's prefix tells Snug which window the text belongs to; the suffix identifies where the text appears.

For example, runtime.progress.heading identifies the main heading in the installation progress window.

Before downloading a required runtime, Snug displays a confirmation dialog where the user can choose to install it or cancel. The wording in this dialog uses the runtime.prompt.* localisation keys.

If the user agrees, Snug opens the progress window and begins downloading, verifying, and extracting the runtime.

These screenshots show examples of the localisation keys available for each dialog and where their messages appear. In normal use, Snug displays the message text associated with each key.

The annotated example below shows the common parts of a runtime dialog. Not every window uses every field: the progress dialog also shows download information, while the Snug launch-error window uses its own launcher.error.* message keys.

Image: The anatomy of a runtime dialog window showing the key suffixes and where they are placed.

Common Localisation Key Suffixes

.title - The title displayed in the dialog window.

.heading - The main heading, which tells the user what is happening.

.subheading - Supporting text immediately below the main heading.

.content - The main explanation or instructions.

.info_heading - A heading for additional information.

.info_subtext - The first line of additional information.

.info_subtext_2 - The second line of additional information.

.button_<name> - The label for an action button, such as .button_cancel or .button_download. Buttons vary according to the dialog.

For example, runtime.progress.content identifies the main explanation in the installation progress window. The key determines where the text appears; a replacement token such as {version} determines which information Snug can insert when the dialog is displayed.

Keep the complete key, including its prefix and suffix, unchanged when editing a localisation file. Change only the text after the equals sign. The message tables later in this section list the actual keys available for each dialog and any replacement tokens they support.

The Runtime Installation Dialogs

Runtime installation is the most interactive part of Snug's launcher. Normally the user only encounters it when a compatible runtime is unavailable. Once the runtime has been obtained and cached, later launches can reuse it without repeating the installation.

The normal installation path is:

Runtime required
Retrieve runtime download information
Ask the user to confirm installation
Download, verify, and extract the runtime
Start the application.

If Snug cannot retrieve the download information, it can offer to open the runtime download page. If installation fails, a retry dialog can offer another attempt or cancellation.

Image: Where Snug may need to ask the user for help.

When Snug Cannot Launch

Snug's launch-error window reports failures handled by the launcher, such as a missing application file or a Java application that cannot start. A failure reported by Windows before launcher initialisation is outside this dialog reference.

You can customise the launcher error window using launcher.error.* keys. Snug fills launcher.error.content with the underlying error message, which can itself be translated using the appropriate err.* key. If the embedded localisation files cannot be read, the window falls back to built-in English.

Message Key Reference

The reference begins with selected keys for each dialog, followed by token meanings, the complete token-bearing key table, and all no-token keys. REPLACEMENT_TOKENS.md in the Snug repository records the machine-checked token contract. For another Snug version, check its reference:

https://github.com/synapticloop/snug/blob/main/REPLACEMENT_TOKENS.md

Or you can run the command

`Command(s)`
`.\snug.exe --list-tokens`

This prints the replacement-token reference for the version of Snug you are using.

Keep every key exactly as shown. “Allowed tokens” lists the tokens a key supports; “Default English tokens” lists only those used by the supplied English wording. “None” means no tokens in that column. You may use any allowed token, even if the default wording omits it.

Runtime Installation Confirmation Keys

Use runtime.prompt.* for the installation confirmation dialog.

Image: The anatomy of a runtime dialog window showing the key suffixes and where they are placed.

The selected keys below cover its explanation and action buttons. The complete reference later includes its headings and information text.

Localisation Key	Description and allowed tokens

`runtime.prompt.content`	the explanation; may use `{version}`, `{size_mb}`, and `{sha256}`.
`runtime.prompt.button_cancel`	the cancel button (no replacement tokens).
`runtime.prompt.button_download`	the download button; may use `{version}`, `{size_mb}`, and `{sha256}`

Downloading and Preparing the Runtime

Use runtime.progress.* for the download, verification, and extraction progress window.

Image: The runtime installation progress window, showing the localisation keys used for its messages and progress information.

The progress dialog also supports title, heading, subheading, and informational text keys. These fields do not accept replacement tokens.

Localisation Key	Description and allowed tokens

`runtime.progress.content`	the main progress message; may use `{version}` and `{size_mb}`.
`runtime.progress.phase_label`	the current download phase; may use `{arch}`.
`runtime.progress.pct_label`	the percentage display; may use `{pct}`.
`runtime.progress.detail_with_size`	downloaded amount and speed; may use `{done_mb}`, `{total_mb}`, and `{speed_mb_s}`.
`runtime.progress.detail_no_size`	progress when a total size is unavailable; may use `{pct}`.
`runtime.progress.detail_eta_seconds`	remaining seconds; may use `{n}`.
`runtime.progress.detail_eta_done`	the message shown when the download is almost finished (no replacement tokens).

When the Download Service Cannot Provide the Runtime

This dialog may appear when Snug cannot retrieve runtime release information, for example, because the network is unavailable or the download service cannot be reached.

Image: The anatomy of a runtime dialog window showing the key suffixes and where they are placed.

Use runtime.metadata_failed.* when runtime release information cannot be retrieved. The subheading allows {major}; the content allows {major} and {error}. The other keys in this group accept no tokens.

The default English content is Technical detail:\n{error}. It uses {error} only; a custom value may also use {major}.

Localisation Key	Description and allowed tokens

`runtime.metadata_failed.subheading`	`{major}`
`runtime.metadata_failed.content`	Allowed tokens: `{major}`, `{error}`. Default English tokens: `{error}`.
`runtime.metadata_failed.button_cancel`	None
`runtime.metadata_failed.button_open_browser`	None

Retrying a Runtime Download

Use runtime.retry.* for the retry dialog following a download, verification, or extraction error. Its token contract is listed below.

Image: The anatomy of a runtime retry dialog window showing the key suffixes and where they are placed.

Localisation Key	Description and allowed tokens

`runtime.retry.subheading`	`{version}`, `{attempt}`, `{max_attempts}`, `{error}`
`runtime.retry.content`	`{version}`, `{attempt}`, `{max_attempts}`, `{error}`
`runtime.retry.button_retry`	None
`runtime.retry.button_cancel`	None

When Runtime Installation Cannot Complete

Use runtime.failure.* for the final installation failure dialog. Metadata retrieval and retry dialogs have separate message groups.

Image: The runtime installation failure dialog, showing the localisation keys used for its messages and button.

runtime.failure.content allows {version} and {error}. The retry entries below are repeated for convenience; their contracts are unchanged.

Localisation Key	Description and allowed tokens

`runtime.failure.content`	the failure explanation; may use `{version}` and `{error}`.
`runtime.retry.subheading`	the retry message; may use `{version}`, `{attempt}`, `{max_attempts}`, and `{error}`.
`runtime.retry.content`	additional retry information; may use `{version}`, `{attempt}`, `{max_attempts}`, and `{error}`.
`runtime.retry.button_retry`	the retry button (no replacement tokens).
`runtime.retry.button_cancel`	the cancel button (no replacement tokens).

Snug Launcher Error Window

Use launcher.error.* for Snug's launch-error window. These keys do not customise failures reported by Windows before launcher initialisation.

Image: The launcher error window, showing the localisation keys used for its messages and buttons.

Localisation Key	Description and allowed tokens

`launcher.error.content`	the explanation; may use `{error}`.
`launcher.error.info_subtext_2`	additional information; may use `{update_check_url}`.
`launcher.error.button_exit`	the exit button (no replacement tokens).
`launcher.error.button_update`	the update button (no replacement tokens).

The selected dialog keys above are a starting point. The complete reference below also covers Java, file, splash-screen, and platform errors handled by Snug.

Replacement Tokens and the Key Reference

Replacement Token	What Snug puts in its place

`{0}`	positional slot - the single argument this key is handed, usually an error message
`{actual}`	byte length the pixel buffer turned out to have
`{arch}`	target architecture label, e.g. "Windows x64"
`{attempt}`	which attempt this is, counting from 1
`{computed}`	the SHA-256 the launcher calculated from the downloaded file
`{declared}`	the SHA-256 the publisher advertised
`{done_mb}`	megabytes downloaded so far
`{error}`	the underlying error, already localised when it is a launcher error
`{expected}`	byte length the buffer's dimensions require
`{found}`	the Java major version actually found on the machine
`{library}`	the library that failed to load
`{major}`	the Java major version the runtime metadata lookup was for
`{max_attempts}`	total number of attempts configured
`{message}`	the OS-level error text explaining the failed load
`{min_java}`	the Java major version the application requires
`{n}`	whole seconds of estimated time remaining
`{name}`	name of the metadata field that was malformed
`{path}`	a filesystem path that was located, or searched
`{pct}`	completion percentage as a whole number
`{sha256}`	the SHA-256 digest the download is verified against
`{size_mb}`	approximate download size in megabytes
`{speed_mb_s}`	current download speed in MB/s
`{symbol}`	the exported symbol that was missing from it
`{total_mb}`	total megabytes to download
`{update_check_url}`	the URL supplied through the builder's --update-url option, used to check for a newer release
`{value}`	the value the launcher received for that field
`{version}`	the JDK release being downloaded or installed, e.g. "25.0.1+9"

IMPORTANT: A replacement token is only available where Snug supplies its value. For example, {size_mb} is supported by the download-confirmation and current progress messages, but not by runtime.retry.subheading. If you put an unsupported or misspelt token into a message, Snug leaves it visible literally instead of replacing it. Keep the braces, spelling, and case exactly as documented.

Keys and Their Allowed Tokens

This complete table lists every token-bearing key. “Allowed tokens” defines what a custom value may use; “Default English tokens” describes the supplied English value. None means no tokens in that column. Tokens are optional, but any token you use must be allowed for that exact key.

Localisation File Key	Allowed tokens	Default English tokens

`err.format`	`{0}`	`{0}`
`err.invalid_state`	`{0}`	`{0}`
`err.io`	`{0}`	`{0}`
`err.java_exception`	`{0}`	`{0}`
`err.jni_attach`	`{0}`	`{0}`
`err.jni_create`	`{0}`	`{0}`
`err.jni_init`	`{0}`	`{0}`
`err.jni_invoke`	`{0}`	`{0}`
`err.main_class_not_found`	`{0}`	`{0}`
`err.no_main_method`	`{0}`	`{0}`
`err.self_path`	`{0}`	`{0}`
`err.zip`	`{0}`	`{0}`
`err.jvm_not_found`	`{min_java}`	`{min_java}`
`err.jvm_too_old`	`{path}` `{found}` `{min_java}`	`{path}` `{found}` `{min_java}`
`err.library_load`	`{library}` `{message}`	`{library}` `{message}`
`err.symbol_not_found`	`{symbol}` `{library}`	`{library}` `{symbol}`
`jdk.err.bad_metadata_shape`	`{0}`	`{0}`
`jdk.err.dialog`	`{0}`	`{0}`
`jdk.err.download`	`{0}`	`{0}`
`jdk.err.extract`	`{0}`	`{0}`
`jdk.err.io`	`{0}`	`{0}`
`jdk.err.metadata_fetch`	`{0}`	`{0}`
`jdk.err.no_java_exe`	`{0}`	`{0}`
`jdk.err.no_metadata_for_version`	`{0}`	`{0}`
`jdk.err.bad_field`	`{name}` `{value}`	`{name}` `{value}`
`jdk.err.sha256_mismatch`	`{declared}` `{computed}`	`{computed}` `{declared}`
`splash.err.thread_spawn`	`{0}`	`{0}`
`splash.err.buffer_length`	`{expected}` `{actual}`	`{actual}` `{expected}`
`launcher.bare_stub.no_payload`	`{path}`	`{path}`
`launcher.error.content`	`{error}`	`{error}`
`launcher.error.info_subtext_2`	`{update_check_url}`	`{update_check_url}`
`runtime.prompt.content`	`{version}` `{size_mb}` `{sha256}`	`{size_mb}`
`runtime.prompt.button_download`	`{version}` `{size_mb}` `{sha256}`	`None`
`runtime.metadata_failed.subheading`	`{major}`	`None`
`runtime.metadata_failed.content`	`{major}` `{error}`	`{error}`
`runtime.progress.content`	`{version}` `{size_mb}`	`{version}` `{size_mb}`
`runtime.progress.phase_label`	`{arch}`	`{arch}`
`runtime.progress.pct_label`	`{pct}`	`{pct}`
`runtime.progress.detail_with_size`	`{done_mb}` `{total_mb}` `{speed_mb_s}`	`{done_mb}` `{total_mb}` `{speed_mb_s}`
`runtime.progress.detail_no_size`	`{pct}`	`{pct}`
`runtime.progress.detail_eta_seconds`	`{n}`	`{n}`
`runtime.failure.content`	`{version}` `{error}`	`{version}` `{error}`
`runtime.retry.subheading`	`{version}` `{attempt}` `{max_attempts}` `{error}`	`{attempt}` `{max_attempts}`
`runtime.retry.content`	`{version}` `{attempt}` `{max_attempts}` `{error}`	`{error}`

Image: Message keys identify the text shown in the progress dialog. Replacement tokens insert live values, such as the runtime version, download size, and percentage complete.

IMPORTANT: Keys not listed in the token-bearing table do not accept replacement tokens. A token placed in one of those keys is displayed literally. The remaining keys are listed by group below so that this chapter can be used as a complete reference.

Keys Without Replacement Tokens

The keys below are also available in the English localisation catalogue. They do not accept replacement tokens. Keep the key names unchanged, and edit only their values.

The table groups no-token keys by dialog or purpose, with one key per line.

Dialog Window	Localisation Key

Launcher and Java errors	`err.no_main_class` `err.unsupported_platform` `launcher.bare_stub.hint` `launcher.bare_stub.command`



Snug launcher error window	`launcher.error.title` `launcher.error.heading` `launcher.error.subheading` `launcher.error.info_heading` `launcher.error.info_subtext` `launcher.error.button_exit` `launcher.error.button_update`






Runtime installation progress	`runtime.progress.title` `runtime.progress.heading` `runtime.progress.subheading` `runtime.progress.arch_macos_arm64` `runtime.progress.arch_macos_x86_64` `runtime.progress.arch_windows_x86_64` `runtime.progress.detail_eta_second` `runtime.progress.detail_eta_done` `runtime.progress.info_heading` `runtime.progress.info_subtext` `runtime.progress.info_subtext_2`
Runtime metadata, retry, and failure dialogs	`runtime.metadata_failed.title` `runtime.metadata_failed.heading` `runtime.metadata_failed.info_heading` `runtime.metadata_failed.info_subtext` `runtime.metadata_failed.info_subtext_2` `runtime.metadata_failed.button_open_browser` `runtime.metadata_failed.button_cancel` `runtime.retry.title` `runtime.retry.heading` `runtime.retry.info_heading` `runtime.retry.info_subtext` `runtime.retry.info_subtext_2` `runtime.retry.button_retry` `runtime.retry.button_cancel` `runtime.failure.title` `runtime.failure.heading` `runtime.failure.subheading` `runtime.failure.info_heading` `runtime.failure.info_subtext` `runtime.failure.info_subtext_2` `runtime.failure.button_label`
Runtime installation confirmation	`runtime.prompt.title` `runtime.prompt.heading` `runtime.prompt.subheading` `runtime.prompt.info_heading` `runtime.prompt.info_subtext` `runtime.prompt.info_subtext_2` `runtime.prompt.button_cancel`






Splash, platform, and generic messages	`splash.err.overflow` `splash.err.empty` `splash.err.bitmap` `splash.err.window` `splash.err.update_layered` `splash.err.create_compatible_dc` `splash.err.create_dib_section` `splash.err.create_window` `splash.err.update_layered_window` `splash.title` `generic.error_dialog_ok` `generic.info_dialog_continue`

Previewing Your Changes

You do not need to rebuild an executable every time you change a sentence. The separate snug_preview.exe utility can show launcher dialogs in their intended context, including unusual runtime-error states that are inconvenient to reproduce during ordinary testing.

By default, the preview uses the Snug Preview icon. To see the dialogs with your application icon, start it with:

`Command(s)`
`.\snug_preview.exe --icon "my-app.ico"`

To load a single localisation file or an entire directory, use --localisation. The language dropdown always includes English (en). Loading one German (de) file therefore offers de and en; loading a directory makes each available language selectable.

`Command(s)`
`.\snug_preview.exe --localisation "snug\localisation" --icon "my-app.ico"`

Open the preview with your localisation file or directory, select the language, and inspect each changed dialo g.

Check that headings explain the situation, buttons describe their actions, and translations fit. Snug Preview displays sample dialog states; also test the packaged application before release.

Note: Close all open preview dialogs and restart snug_preview.exe after editing a localisation file to see your latest changes.

Other Languages

Localisation allows the same Windows executable to show launcher messages suited to the language selected by Windows. This is particularly useful when the Java application itself already supports more than one language.

Keep each language's messages in its own localisation file, or provide a directory containing the files. The built-in English messages remain available as a fallback when Snug cannot select a suitable translation. You can preview each language before building.

Image: The same runtime dialog shown in English and German. The German wording is an illustrative translation for testing.

Before You Build: Final Checks

Before building, check:

• Keep every localisation key unchanged; edit only its value.

• Use only tokens allowed for that exact key, with braces, spelling, and case intact.

• Save each language file and restart Snug Preview to load your edits.

• Preview every changed dialog and language; check headings, line wrapping, button labels, and unexpected literal tokens.

• Have translations checked by a fluent speaker.

• Supply the intended file or directory through --localisation in snug.options (see Section 4: Configuration Options).

• Build and run the packaged application on Windows; check the messages in the launch and runtime scenarios you can reproduce. Preview alone does not verify runtime behaviour.