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.
Invoering
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
Hier’s how the folder structure for translations looks like:
Shardpunk root folder Data Languages <-- this is where the predefined, default language (Engels) is located ~mods <-- this is where you will be adding your mods that you want to upload to Steam Workshop
Hier’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.
Belangrijk: 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
De manifest.json file is used by the game to read basic mod information. It should have the following structure:
{
"displayName": string,
"beschrijving": string,
"auteur": string
}
De displayName en beschrijving fields hold the name and description of the Workshop item that will be created.
De auteur 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.
De 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,
"ingeschakeld": boolean ("WAAR" | "false")
}
De 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.
De ingeschakeld 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 de meeste gevallen, the names of translation keys should be self-explanatory. Bijvoorbeeld, “weaponModification_StunModule_name” is about the name of the stun module weapon modification, en “skill_sociopath_desc” is about the description of the “sociopath” vaardigheid. When in doubt, refer to the English translations.
Special feature: dynamic translation keys
The game displays random character messages during different combat/shelter situations. Bijvoorbeeld, 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.
De characterType part allows you to define which character will be allowed to use this text. “gewoon” 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, Echt. 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.
Voorbeeld: 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. Gebruiken “\n” to put line breaks in a translation value.
- Curly brackets “{“ / “}” are used for formatting. Voorbeeld:<
"{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” map, with correct folder structure and all required files, zoals hierboven beschreven.
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=”WAAR” in de <Config> element. Voorbeeld:
<Config DevMode="WAAR" ActiveFontType="Origineel" 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?
Ja, 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!
Eerst, 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.
