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.
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:
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:
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.