Create a New Language - NBKRedSpy/Stacklands-NewLanguageLoader GitHub Wiki

Questions

If you have any questions about creating new languages, I can be found on the Stacklands modding channnel (#stacklands-modding) at https://discord.gg/mXmSncG7

I'm NBK_RedSpy on that channel.

Preface

This document may be fairly long, but don't be discouraged. The process is simply creating a couple of text files and (if necessary) importing a font.

Creating a New Language

To create a new language, only a text editor is needed. However, it is easier to edit the Tab Separated localization.tsv with a spread sheet program such as Google Sheets, Libre Office, Excel, etc.

Setup

Subscribe to the Stacklands Language Loader mod on the Steam Workshop. Steam Workshop Page

Download the TestLanguage.zip template on the releases page.

Important: When using the template files, make sure to replace "Test Language" in the templates and rename the folder. This will be described in the sections below.

Extract Template

Extract that TestLanguage.zip into a directory and rename the TestLanguage folder to the new language's name. For example, KlingonLanguage.

There will be the following files in the folder:

File Description
add-language-info.json Defines the language info such as name.
localization.tsv Contains all the translated text.
manifest.json The Stacklands' mod manifest (same format as regular mods).
Icon.png The icon that will be shown on the Steam Workshop for the mod.

add-language-info.json

Open the add-language-info.json file.

Contents Example:

{
    "ColumnLanguageName": "Test Language",
    "UnityLanguage": "Unknown",
    "NativeDisplayName": "^_^ Test ^_^"
}

Change the ColumnLanguageName to the name of the language in English. This will be the "English" version of the name shown in the language options as well as the column for the translated text in the localization.tsv.

For the UnityLanguage, use the language name that matches in the SystemLanguage page found here. If the language is not in that list, use "Unknown".

If the UnityLanguage is set, it allows the game to default to the computer's language. Otherwise, the user will need to manually set the language in the game's options.

Change the NativeDisplayName to the native name of the language. For example, Italian would be Italiano.

manifest.json

Example:

{
    "name": "Test Language",
    "id": "Test_Language",
    "version": "1.0.0",
    "dependencies": [
        "Stacklands_NewLanguageLoader"
    ]
}

This is the mod information file for Stacklands.

name: Change to the name of the mod. This is displayed as the name in the mod list. id: Change to a unique id for the mod. For example, YourSteamName.ItalianLanguage. Make sure the id is unique. If someone else creates a mod with the same id, the mods will not load if both are installed. version: The version number shown in the Mod's details. Increment when a new version is uploaded. dependencies: This must include Stacklands_NewLanguageLoader as shown above.

icon.png

This is the icon that will be shown on the Steam Workshop page. There is a default icon, but it can be changed to be any icon. It just needs to be a icon.png or icon.jpg, and is generally 512x512 or 1024x1024 in size.

localization.tsv

The format of the localization.tsv file is described here:

https://modding.stacklands.co/en/latest/guides/localization.html

The difference is that this mod's localization.tsv file should contain only two columns: "Term", and a column name specified in ColumnLanguageName, which was set in the add-language-info.json.

Ignore the part of the documentation which talks about using the file. The localization.tsv file only needs to be present in your mod's folder. The Stacklands New Language Loader will handle adding it to the game.

Example:

Term	Test Language
label_quit	😎 Quit 😎
label_back	😎 Back 😎

Tabs vs Spaces

Important: If using a text editor to create the file instead of a spreadsheet, make sure the there are tabs between columns and not spaces. For example, if using Visual Studio Code, pressing tab will write out four spaces instead of a tab character.

Translation Terms List

To get the full list of terms to translate, the Stacklands New Language Loader has the ability to save all of the game's default translations to a lang.tsv file.

To enable, go to the game's main menu and navigate to Mods -> Stacklands New Language Loader.

Alt text

Click the Dump Game's Localizations entry to turn it on. When returning to the previous menu, the game will automatically restart.

The next time the game is loaded, a lang.tsv file will be created in the "Stacklands New Language Loader" folder. The easiest way to find the folder is in the mod's details screen. Go to the main menu -> Mods -> Stacklands New Language Loader. At the bottom of the screen is the "Open Folder" button. Clicking the button will open the mod's folder which will contain the lang.tsv file.

Example:

Term	Notes	English	Dutch	French
card_animal_pen_description		Can hold 5 Animals	Hier kunnen 5 Dieren in	Peut accueillir 5 Animaux
card_animal_pen_name		Animal Pen	Dierenverblijf	Enclos

The contents of the lang.tsv's `Term`` column should be added to your localization.tsv file. Put the translated text for the new language in the second column.

Do not copy any other columns from the lang.tsv file into your localization.tsv file.

Short Translations

It is not necessary to translate every line of text in the game, but it is helpful. If a game's term is not in the localization.tsv file, the game will fallback to the English text.

Special Values

Use the # character to add a new line to the text.

Some variables are used in the translated text. For example, the text line may have "Continue Game [Moons] moons" which will be shown as "Continue Game 30 moons". Do not translate the text in the brackets.

Warning: Do not post the lang.tsv file or existing translations. This is owned by SokPop and should not be distributed.

Copy the term key from the first column and add to your localization.tsv file's first column. (Ex: card_animal_pen_name) Write the translated text to your localization.tsv file's second column. (Ex: The translation for "Animal Pen") Repeat for all rows.

Custom Fonts

The game's base font may already have the characters needed for a language to work in the game.

However, the characters for every language are not included.

It is recommended to translate the text first, then open the game and see if there are boxes instead of characters in the text.

For example:

Example of text missing characters

In the image above, several of the characters are missing and show boxes instead.

In this case, a font will need to be added to the mod.

See Importing Fonts

Testing

To test the mod, copy your mod's folder to Stacklands mod testing folder. On Windows, the folder is at %localappdata%low\sokpop\Stacklands\Mods.

When running the game, your mod should be listed in the Mods screen. Select your language by going to the main menu -> options -> language. Your language should be in the list. Select the language. If you have translated the label_back term, then the back button at the bottom of the screen should have changed to your mod's translated text.

The game will remember your language selection the next time the game is run.

To test cards, start or continue a game and open the Debug Menu by pressing K, O, and F1 at the same time. There will be a Cards tab in the dialog. You can click on a card to spawn it on the board. However, the card list should already reflect any card names your mod has translated.

Uploading to Steam Workshop

When testing is completed, you can now upload the mod to the Steam Workshop. Follow the Stacklands modding wiki entry for uploading found here https://modding.stacklands.co/en/latest/guides/publishing.html

After uploading, make sure to add the Stacklands Language Loader as a dependency. It will be on your mod's page, on the lower right:

Mod's Steam dependency screen shot

Translating other Mods

It is possible include translated text for other mods. If the other mod has a localization.tsv, add the key from their mod to your localization.tsv and add a translation. If the other mod is not loaded or is missing, the extra localization.tsv entries will simply be ignored and will not affect the game.

It is preferable to request the author of the mod to add a translation to their mod. This will not affect their mod since language columns that are not used are ignored by the game.