Translations, Fonts, and Character Sets in Banished

[catty-cb 4,412]

The first example, in /example/translation, shows a translation of all the strings in the game. It also changes the font and adds new characters to the font that are in use. Take a look in the /example/translation folder. It contains a mirror of some of the resources in the game, except they've been changed.

The example translation makes all text uppercase, and changes any vowels to have accents above them. Note that there are special characters in strings you'll want to keep intact - the help files have things like (^f0, ^jl, etc). Strings also have '~~' (for tilde) '~"' for quote, and @N (for substitution, where N is 0..9). During translation, you'll have to keep the escape characters intact.

First, you need to define the character set you want to use. You can view a character set example in /example/translation/Font/CharacterSet.rsc

// this file needs to be UTF16 little endian if it contains characters over index 255
// fonts that use this character set need to support all the characters listed here.
// This file is used to keep the font textures small, instead of having to include thousands of characters
// ~ is a special escape character, so ~~ is required to add tilde to the set, ~" is needed for quotation marks
CharacterSet resource
{
	String _characters = "
		// Special escape characters
		~~ ~"
		// Punctuation
		`!@#$%^&*()_+-={}|[]\:;'<>?,./©
		// Numbers
		01234567890
		// characters for English (no lower case, note: help text will not display correctly)
		ABCDEFGHIJKLMNOPQRSTUVWXYZ 
		abcdefghijklmnopqrstuvwxyz 
		// additional characters for this example
		ÂÊÎÔÛ
	";
}

Next, you'll change the fonts for the game. There are four main fonts, each a different size. A font resource looks like this:

Font resource
{
	// reference character set
	CharacterSet _characterSet = "Font/CharacterSet.rsc"; 
	
	// whatever font you want, has to be loaded into windows
	String _fontName = "Arial"; 
	
	// height in pixels of the font
	int _fontHeight = 24; 
	
	// name of the sprite sheet to create, and its size. You may have to increase the size of 
	// the sheet to contain all the characters
	String _sheetName = "Build/FontSheet.rsc";
	int _sheetWidth = 256;
	int _sheetHeight = 128;
	
	// name of the material that uses this font. The material needs to reference 
	// the correct texture.
	String _materialName = "Font/FontMaterial.rsc";
	
	// the texture to output with all the glyphs on it. 
	String _imageName = "Build/uiFontImage.png";
}

Finally, you can translate all the text. All text is contained in string tables that look like this:

StringTable common
{
	Entry _strings
	[ 
		{ String _name = "Ok";					String _text = "ÔK"; }
		{ String _name = "Cancel";				String _text = "CÂNCÊL"; }
		{ String _name = "Yes";					String _text = "YÊS"; }
		{ String _name = "No";					String _text = "NÔ"; }
		{ String _name = "Apply";				String _text = "ÂPPLY"; }
		{ String _name = "Next";				String _text = "NÊXT"; }
		{ String _name = "Quit";				String _text = "QÛÎT"; }
	]
}

Note: If Unicode characters are required to support characters, resources files can be saved as USC-2, little endian. If you're unsure, the CharacterSet.rsc file is already in this format.

Depending on the translations and size of the text, some dialogs may not contain the text, or become misshapen. To remedy this, you could also modify parts of the user interface layout to accommodate the translation more fully.

For ease of building the mod, a single ExternalList resource is provided that references all the changed resources. To build this mod, run the command

bin\x64\Tools-x64.exe /build Package.rsc:list /pathres ../example/translation /pathdat ../example/translation/bin

You should now be able to run the game with the command:

bin\x64\Application-x64-profile.exe /pathres ../example/translation /pathdat ../example/translation/bin

You'll see that the translation has taken effect. However, this has just modified the game data locally - this is great for quick development and iteration, but if you wanted to give this mod to others, you'd need to package it.

First, you'll create a definition for the package (see /example/translation/Package.rsc)

PackageFile translationExample
{
	String _name = "Translation Example";
	String _author = "Shining Rock Software, LLC";
	String _description = "This mod changes the font from the default to Arial. 
		It also modifies the default character set. All text strings
		are made uppercase and vowels have accents over them.";
	String _icon = "icon.png";	// must be 48x48
        String _preview = "preview.jpg"  // preview image used for Steam Workshop, must be square, png or jpg.
	int _userVersion = 1;

	// all files in resource directory (each item is searched recursively)
	String _includeList
	[
		"*"	
	]
	
	// exclude package files, mod files, file used for building packages
	String _excludeList
	[
		"Package_*.crs"
		"*.pkg"
		"*.pkm"
	]
}

Next, you'll compile the package using the /mod parameter.

bin\x64\Tools-x64.exe /mod Package.rsc:translationExample /pathres ../example/translation /pathdat ../example/translation/bin

Building the mod package may take some time, depending on how many resources are in the data directory and how many have been modified. The tool checks the new resources against the ones contained in the game, and only packages files that have changed or are new. The tool will output files that it is packaging, so you can see what you've modified or added.
In the end, this will output a file called translationExample.pkm in the bin/WinData folder.

Next, test the mod properly.

1. When you start the game, start it so it only uses packages.

   bin\x64\Application-x64-profile.exe /onlypkg

   All the text should be as normal.
2. Open the Mod dialog by pressing the 'Mods' button.
3. The Translation Example mod should be listed in the dialog.
4. Enable it by checking the X button next to the text that says Enable.
5. Press OK.
6. The menu will prompt you to reload, and after doing so the mod will be in effect.
7. Once everything is working as intended in a mod, you can distribute the .pkm file to other users. All they have to do is place the .pkm file in the WinData folder, and then enable the mod in game.

  Edited November 12, 2023 by catty-cb  
Banished Toolkit 1.0.7