Localization

The following contains in-depth technical documentation on how to use TS!UNDERSWAP's localization systems.

The bottom of the page contains a list of frequently asked questions about the less-technical aspects.

If you have any further questions or concerns, don't hesitate to join our Discord server to talk to us!

This page will be updated as new changes occur in the localization system. This current information is up-to-date as of Demo 2.0.8. To see the old documentation for Demo 1.0, go here.



Debug Mode

DISCLAIMER: Using debug mode can seriously corrupt your game saves and files. Use it at your own risk. Savedata produced in debug mode may cause errors and crashes in later releases of the game, as well.

Additionally, no official support is provided for using debug mode, even if you break your game using it. These features are subject for change and removal at any given time.

How to enable on Windows

Relevant Commands

Listed here is a subset of debug mode commands that are useful for localization purposes in demo 2.0. More commands exist, but are not documented here.



How to Make a New Language

Getting Started

Step 1: In the game's data folder, create a lang folder if one does not already exist. Here, you can put localization files for any number of languages installed.

Step 2: Copy the game's default.json file from the data folder into the lang folder. Rename it to something unique for your language, and customize it in a text editor of choice!

Step 3: You will want to make a new folder for your language's remaining data files (including text, sprites, sounds). This will be what you use for the directory in the JSON file you made a copy of.

What's all of this JSON stuff?

See the below section that goes into detail. JSON is a common file format used to represent data.

Distribution

To distribute unofficial language patches, you can ZIP up your files (including the copied JSON) and share it with others. On older versions of the game, people may be required to create a lang folder to extract to, but once official localization patches exist, it should be there automatically.

If you would like to make an unofficial localization patch official, we are open to manually reviewing the patches. However, we will need proper verification that it is of good quality. We're open to talk on our Discord server!



Localization File Structure

JSON Config File

Translation File Types

There are multiple formats that can be used to represent the text data of a language. Here's a list:

You can get the base English translation files used in Demo 2.0.7 here! You can choose either version you prefer to work with, and convert between as you see fit.

Note: Old translation files from Demo 2.0.6 can be found here, for comparison/upgrade purposes.

When used as part of a language (by updating diannex in the config JSON file), these files will override all of the existing in-game text.

Converting Between Translation File Types and Versions

Translation files are built on a system called Diannex, which has a command-line tool used to convert between types. It currently supports 64-bit Windows officially, but can be manually built for other platforms.

To use the Diannex tool, you can download the version used by TS!UNDERSWAP from GitHub.

Note: If your browser or antivirus believes Diannex is malware, try to allow the file to download and run anyway. It's a false positive due to the EXE not being commonly downloaded.

You'll want to put diannex.exe into a folder with your all of your translation files. Make sure to back them up before running anything. When there, open a command line or terminal in that folder (or navigate to that folder using the cd <path> command). Then, you have multiple options for commands to run:



Text Formatting

TS!UNDERSWAP has custom text formatting syntax used for dialogue, as well as some menus and UI. This section will describe some of it.

Mid-Text Commands

Everything enclosed with two ` characters is not displayed on screen. They signify a "mid-text command," and can change properties of the text.

The first character after the opening ` tells the type of command. Following that is any parameters, such as a specific text color/effect. After the parameters is the closing ` character.

Here's a list of useful commands to know:

Additional Formatting

You can insert new lines of dialogue to the game!

You can remove lines of dialogue from the game! (To an extent.)

You can change and add face portraits/characters to lines of dialogue!

Frequently Asked Questions

Q: What languages are currently supported?

A: In addition to English, the following languages are currently supported:

We also plan to support the following languages:

These are developed by community localizers in their spare time, and will be released whenever they're ready. This process takes a while, so please be patient!

Q: What types of localizations are there?

A: The game has three different types of languages:

Q: How do I get my localization added to the game?

A: We generally evaluate patches on a case-by-case basis, and once substantial progress has been made.

Before anything, you'll want to join our Discord server and voice your intent in the #localization channel. It's important to communicate with us -- asking questions about the writing, how to translate certain material, consulting us about dialogue changes, and sharing your progress.

Most importantly, patches must fulfill the below guidelines to be considered for implementation.

Q: What are the guidelines for verified community localization patches?

A: It must be fully and accurately translated. This includes:

If a patch is added in-game, but is found to have violated our guidelines after, it may be removed.

Q: The official localization tools do not support something from my language. Can they be updated?

A: We may be willing to integrate certain changes to the base game if necessary (i.e. fonts, text rendering features, fixes, etc.) This will depend on our free time, though.

Q: Will localizations be updated at the same time as major game updates?

Unfortunately not, and we can't give an estimated timeframe on when they would be. Localizations aren't updated at the same time that the game is developed, and are done afterwards by volunteer translators independent of the team.

When the game receives a major update (i.e. Demo v1.0 to v2.0), older patches will not be included until they have been fully updated -- both for new content, and potential changes to existing material in the script.

Q: My localization was added to the game. Am I required to update it for major game updates?

A: Absolutely not. Making a localization patch should be treated as a hobby, and not an obligation. If you would like someone else to update it for you, then we will see if any native speakers in the community are interested.

Q: My localization was added to the game, but I want it to be removed. Can it be?

A: Yes. If you want your localization removed for any reason, you can request it and we'll uphold that.

Q: I want to create a localization patch, but don't want it added to the game. Can I distribute it on my own?

A: Of course! We ask that you distribute only the necessary files (everything that would go in the lang folder, and a readme with instructions and credit.) Do not redistribute our game.

Q: I'm a native speaker and noticed some inaccuracies in one of the game's verified community localizations. Who can I talk to about this?

A: Join our Discord server and reach out in the #localization channel. Each localization is developed by native speakers in the community, and we're willing to make changes based on feedback.