This guide explains how to put custom translations (including support for new languages, or expanding the existing ones) into the game and upload them to Steam Workshop.
Introduction
Starting from version 1.0.29, Shardpunk is able to dynamically read and import text files holding translation data. This allows for creating mods that can:
- Expand an existing translation with more combat/shelter character texts,
- Create translations for a new language.
Steam Workshop support has been added in version 1.1.7.
Folder structure
Here’s how the folder structure for translations looks like:
Shardpunk root folder
Data
Languages <-- this is where the predefined, default language (English) is located
~mods <-- this is where you will be adding your mods that you want to upload to Steam Workshop
Here’s how a folder structure for a mod should look like:
[Root folder of the mod]
manifest.json ← mod manifest file
preview.png ← workshop item image
Languages\
[Language code folder]
meta.json ← language meta file
[.txt files with actual translations]
[Root folder of the mod] can have any valid folder you like.
“Languages” folder is required.
[Language code folder] holds a language code that the game will use to identify a language. I recommend using ISO 639-1 two-letter codes here, but you can basically use anything you want.
Important: the game will combine all translations from language folders of the same name – even if they come from different mods. So if you want to create a mod that extends/overrides some of the default English translations, the language folder name should be “en”, as that’s the folder name present in the default translations path (“Data\Languages\en”).
manifest.json and preview.png files
The manifest.json file is used by the game to read basic mod information. It should have the following structure:
{
"displayName": string,
"description": string,
"author": string
}
The displayName and description fields hold the name and description of the Workshop item that will be created.
The author field is not used during Steam Workshop integration (as Workshop uses the login name of the currently logged-in Steam User anyway), but you can put information about you in this field.
The preview.png file is used as the main image for the Workshop item.
The meta.json file
The meta.json file should have the following data:
{
"displayName": string,
"enabled": boolean ("true" | "false")
}
The displayName field holds the display text of the language that the mod provides. You should set it to a user-readable text when you are creating translations for a new language. The value of displayName will be displayed in the game’s settings window in the language selection dropdown.
The enabled field allows you to control whether the game should use the translations from your mod.
Translation files
.txt files with actual translations are simple text fields, where every odd line holds a translation key, and every even line holds a translation value. As you might have guessed, every translation file has an even number of lines.
More info on the .txt files:
- They have to have a .txt extension for the game to recognize them.
- The names of these files do not matter.
- Translation keys can appear multiple times in one/multiple .txt files, but it does not really make sense. The latest found translation value always wins (although I don’t load the files in alphabetical order, so I cannot guarantee what will be overridden by what).
In most cases, the names of translation keys should be self-explanatory. For instance, “weaponModification_StunModule_name” is about the name of the stun module weapon modification, and “skill_sociopath_desc” is about the description of the “sociopath” skill. When in doubt, refer to the English translations.
Special feature: dynamic translation keys
The game displays random character messages during different combat/shelter situations. For example, a character might comment on the fact that they’ve killed an enemy, healed an ally or found something of value. When the game determines which text to display in such a situation, it does not look for a specific translation key – it looks for any translation key that matches a certain prefix. Consider this list of translation keys:
combatMessage_EnemyStillNotEncountered_common_1 That's strange. We should be seeing them by now... combatMessage_EnemyStillNotEncountered_common_2 Still no trace of the vermin. combatMessage_EnemyStillNotEncountered_common_3 It's too quiet here.
As you might have guessed, these texts will be used when determining what a character should say if there are no enemies present on a map after a few turns. The general syntax of such dynamic translation keys is as follows:
[combatMessage|shelterMessage]_[eventType]_[characterType][suffix]
There are different eventType values present. Explore the English translation keys to see all of them.
The characterType part allows you to define which character will be allowed to use this text. “common” is allowed to be used by everyone, but if you use character-specific type (you can find all character types in the characters.txt translations file of the English translation), you could create a message that would be only used by a specific character type.
Suffix is anything, really. You might want to make sure that your mod is using an original suffix name to minimize the occurrence of identical keys in other mods.
Example: if you would like to create a combat message specific to Silas, you could write:
combatMessage_EnemyStillNotEncountered_revolverCrazy_myCustomSuffix1 My name is Silas, and I do not like the fact that there are no enemies around.
Translation values
When creating translation values, stick to these rules:
- Every translation value needs to be put in a single line. Use “\n” to put line breaks in a translation value.
- Curly brackets “{“ / “}” are used for formatting. Example:<
"{0}" action now also grants +{1}% crit chance but costs {2} Stress instead.Will be displayed in the game as:
"All In" action now also grants +10% crit chance but costs 4 stress instead.
- Square brackets are used to highlight parts of the text. This is often used when dealing with descriptions. Text put between square brackets will be highlighted in the game.
Uploading language mods to Steam Workshop
Here’s a step-by-step guide to uploading/updating a language mod to Steam Workshop:
1. Create a mod inside the “Data/~mods” folder, with correct folder structure and all required files, as described above.
2. Enable the developer mode in Shardpunk: edit the config.local.xml file located in the game root folder, and change a DevMode=”false” attribute value to DevMode=”true” in the <Config> element. Example:
<Config DevMode="true" ActiveFontType="Original" ActivePlayerProfileId= (...)
3. Run Shardpunk. If the developer mode kicked in correctly, a “Mods” menu item should appear in the main menu:
4. Enter the mods menu. You should see a list of all local mods there, including the one you’ve created:
5. Select your mod and review all its data. If there are any issues with the mod, a tooltip for the warning icon will hold the details:
6. When all the issues are fixed, hit a button to upload/update the mod to Steam Workshop. You’re done!
FAQ
Can I somehow debug the translations’ loading process?
Yes, game logs should hold relevant data. The logs folder of Shardpunk is located at %appData%\LocalLow\Clockwork Pile\Shardpunk.
My translation does not fit into a UI element. What now?
I expect that this might be happening. If there’s no shorter alternative for a translation, just let me know where the problem exists, I will try to adjust the UI.
I am working on a Polish translation and I can see some issues about the UI size already.
My translations are displayed using funny characters in-game!
First, make sure that your .txt files are saved in UTF-8 – this might be enough.
If this won’t solve the issue, it might be that the fonts you’re using are not supported – contact me then.
What about future game updates? My translation might become outdated.
That is correct. Note that if there are any future changes to the translation texts, I will be adding new versions of keys instead of adjusting the existing ones – so the worst-case scenario will be that the game will fall back to English for these particular texts.
