Shardpunk – Language Mod Installation Guide

This guide tells you how to add your own translations, like making the game work in new languages or improving the ones already there. It also shows you how to share these translations on Steam Workshop.

Wstęp

Beginning with version 1.0.29, Shardpunk now has the ability to read and use text files with translation information. This means you can make mods that:

• Add more texts for characters during combat or in shelters to an already existing translation.
• Create translations for a completely new language.

As of version 1.1.7, the game also supports Steam Workshop, making it easier to share and access these mods.

Folder structure

Tutaj’s how the folder structure for translations looks like:

Shardpunk root folder
   Data
      Languages <-- this is where the predefined, default language (angielski) is located
      ~mods <-- this is where you will be adding your mods that you want to upload to Steam Workshop

Tutaj’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.

Ważny: 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 “W”, 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 name and description of the Workshop item you’re making are stored in the displayName I description fields.

The author field doesn’t play a role in Steam Workshop integration because Steam Workshop automatically uses the login name of the currently logged-in Steam User. Jednakże, you can still include information about yourself in this field if you want.

To showcase the Workshop item, the main image used is the preview.png plik. This image is what users will see when they come across your Workshop creation.

The meta.json file

The meta.json file should have the following data:

{
  "displayName": string,
  "włączony": boolean ("PRAWDA" | "FAŁSZ")
}

The display text for the language your mod offers is stored in the displayName pole. This field should be set to user-readable text when creating translations for a new language. The value entered in displayName will be shown in the game’s settings window within the language selection dropdown.

The włączony field gives you the power to decide whether the game should utilize the translations provided by your mod. By adjusting the value of the enabled field, you can control whether or not your mod’s translations are active in the game.

Translation files

.txt files containing actual translations have a straightforward structure. Each odd line within these files represents a translation key, while every even line holds a translation value. It’s important to note that every translation file must have an even number of lines.

Additional details about the .txt files include:

• For the game to recognize them, these files must carry a .txt extension.
• The specific names of these files are not significant.
• Although translation keys can appear multiple times across one or more .txt files, it’s not advisable. The latest discovered translation value always takes precedence. It’s worth mentioning that the files aren’t loaded in alphabetical order, so the override order might not follow alphabetical sequence.

In most instances, the names of translation keys are self-explanatory. Na przykład, “weaponModification_StunModule_name” pertains to the name of the stun module weapon modification, chwila “skill_sociopath_desc” relates to the description of the “sociopath” umiejętność. When uncertain, it’s recommended to refer to the English translations for clarification.

Special feature: dynamic translation keys

The game showcases random character messages in various combat or shelter scenarios. These messages can include a character’s comments on actions like defeating an enemy, healing an ally, or discovering something valuable. When the game decides which text to show in such situations, it doesn’t search for a particular translation key but rather looks for any translation key matching a specific prefix. Here’s an example 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 probably guessed, these texts serve the purpose of deciding what a character should say if there are no enemies present on a map after a few turns. The general syntax for these dynamic translation keys is as follows:

[combatMessage|shelterMessage]_[eventType]_[characterType][suffix]

There are various eventType values available. To discover all of them, examine the English translation keys.

The characterType section enables you to specify which character can use this text. “wspólny” allows usage by everyone, but if you opt for a character-specific type (found in the characters.txt translations file of the English translation), you can create a message exclusive to a particular character type.

The suffix is flexible, allowing you to use an original suffix name for your mod to reduce the likelihood of identical keys in other mods.

Na przykład, if you want to craft a combat message tailored for 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. Używać “\N” to put line breaks in a translation value.
• Curly brackets “{“ / “}” are used for formatting. Przykład:<

  "{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” falcówka, 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=”FAŁSZ” attribute value to DevMode=”PRAWDA” w <Konfig> element. Przykład:

<Konfig DevMode="PRAWDA" ActiveFontType="Oryginalny" ActivePlayerProfileId= (...)

3. Run Shardpunk. If the developer mode kicked in correctly, A “Mody” 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!

Często zadawane pytania

Can I somehow debug the translations’ loading process?

Tak, 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. Co teraz?

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!

Pierwszy, 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.