Guide to FS mod translations

Translations have been quite rare in FreeSpace 2 despite the longevity of the community, so community member Achille44 decided to create this guide, hoping it will motivate some people to join the endeavor. The objective of this tutorial is to explain how to translate FreeSpace 2 mods into non English languages.

This guide will be divided in 2 parts:

1. Internationalization - this part will be interesting for modders who want to make their mod easily translatable, or translators really motivated and who are ready to dive into technical stuff themselves.
2. Localization - this part will focus on the translation itself, so translators can directly skip to this part.

Internationalization (i18n)

Let's start with a bit of wikipedia explanation: "internationalization is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes."

Historically, FreeSpace 2 has always been terrible in terms of internationalization, many parts of the original game were "hardcoded", which means that they were just not translatable, so translations could only be partial. But thanks to the hard work of the SCP devs, most of the game is now translatable.

BUT so far, most of the modders don't use the recent internationalization features for their mods, probably because the process is quite tedious and difficult to maintain. And given the small number of translations and translators, the effort may not seem worth it.

Here is the list of folders/files which may contain strings that need to be internationalized:
/data

• /fiction: if the mod uses visual novel briefings, those cannot handle localized files by just appending the language suffix, unlike fiction viewer files. so you need to adapt the vn script to use XSTR features. You can find an example in the French translation of Solaris.
• /missions:
  • *.fc2 files: all '$Name' properties must use XSTR.
  • *.fs2 files:
    • '$label', '$Callsign', and '$Name' properties must use XSTR.
    • Convert sexp show-subtitle to show-subtitle-text, and then extract hardcoded strings from show-subtitle-text and put them into new messages so they can be translated.
    • Convert ship alt names to sexp variables so that they can be translated via modify-variable-xstr sexp.
    • Convert hardcoded texts in hud-set-text sexp to variables to be treated by XSTR.
    • Convert the special senders to variables in the following sexps: send-random-message, send-message, send-message-list, send-message-chain.
    • Add +Display Name property for all jump nodes.
    • Convert the first sexp parameter to variable for the following sexps: add-nav-waypoint, add-nav-ship, del-nav, hide-nav, restrict-nav, unhide-nav, unrestrict-nav, set-nav-visited, unset-nav-visited, select-nav, unselect-nav, is-nav-visited, lua-mark-ship, lua-mark-wing, ship-create, lua-staged-countdown-start, set-cargo, ship-change-alt-name.
    • Convert the second sexp parameter to variable for the following sexps: change-subsystem-name, lua-mark-subsystem.
    • Convert the fourth sexp parameter to variable for the following sexp: lua-turrethotkey-add.
    • Convert all sexp parameters to variables for the following sexps: set-nav-color, Add-Object-Role.
    • All the new variables must be modified at the beginning of the mission in a new event with the modify-variable-xstr sexp.
    • When using FRED, check 'Always save Dipplay Names' in the Settings to allow the use of ship display names. Keep in mind that the ship display names are not added automatically by Fred, so you'll have to edit the file manually to add them.
• /tables:
  • Controlconfigdefaults.tbl: all '$Text' properties must use XSTR.
  • credits.tbl and *-crd.tbm files: all lines to be translated must be wrapped into XSTR function.
  • cutscenes.tbl and *-csn.tbm files: all '$Name' properties must use XSTR.
  • hud_gauges.tbl and *-hdg.tbm files: all 'Text' properties must use XSTR.
  • mainhall.tbl and *-hall.tbm files: all '+Door description' properties must use XSTR.
  • medals.tbl and *-mdl.tbm files: all '$Alt Name' and '$Name' properties must use XSTR.
  • rank.tbl and *-rnk.tbm files: all '$Name' properties must use XSTR.
  • *-sct.tbm files: all strings displayed in-game must use the ba.XSTR() function.
  • ships.tbl and *-shp.tbm files:
    • All ships must have an '$Alt Name' property with XSTR. If the ship is present in different files (using +nocreate), you only need one $Alt Name.
    • For each '$Subsystem', unless it is 'untargetable' or it's 'afterburner', you'll need to add '$Alt Subsystem Name' (and '$Alt Damage Popup Subsystem Name' only for playable ships) with XSTR.
    • '+Tech Description' and '+Length' (only the one before '$thruster') must use XSTR.
  • weapons.tbl and *-wep.tbm files:
    • All weapons must have '$Alt Name', '+Title' and 'Tech Title' properties with XSTR. If the ship is present in different files (using +nocreate), you only need one $Alt Name.
    • '$Turret Name', '+Description' and '+Tech Description' properties must use XSTR.

In order to automate the process of internationalization across several mods, I developed a tool to do most of the work automatically. You can try it here if you are interested: https://codeberg.org/AchilleParmentier/FreeSpace2TranslationTools/releases.

Localization (l10n)

It may seem obvious, but before you start translating a mod, you should first ask the authors for permission to avoid any unpleasant surprises.

Setting your language

The first step of any translation is to make your language supported by the game. To do so, create a file with the *-lcl.tbm pattern (e. g. fr-lcl.tbm) with the following content:

$Language: French
+Extension: fr
+Special Character Index: 164

#End

$Language property is the name of the section you will have to use in all the strings/tstrings files where you put your translations. This name will also be displayed in the language choice in the in-game settings. +Extension property is the suffix you will use in all the language-specific files (see the list in the next chapter).

Note that this step is not required if you translate a mod not using SCPUI with the French, German and Polish languages, as they are already supported by the original game.

In case your language uses special characters not provided by the original fonts

In such case, you'll need an extra step to use another font. I can't help you to find what font you need to use, but you'll need to use a ttf file. Once you have found your desired font file, put it into /data/fonts.

Then you have to tell the mod to use that font instead of the original file. To do so, find the fonts.tbl (and/or *-fnt.tbm) file in /data/tables, and change the $TrueType property with the name of your new font file for each font you want to change.

Be aware that your new font might have a different size from the original and change how the text is displayed ingame. In that case you can modify the +Size, +Top offset and +Bottom offset properties to try to replicate the original display.

The files to translate

From here we consider the mod we want to translate is technically ready, so as a translator I just want to know where to find the texts to translate.

Regarding the tools, all txt/tbl/tbm files are simple text files and can be opened and modified with any text editing software, like notepad++ or VSCode.

You'll find below the list of folders/files which can contain texts to be translated.

Fiction

The *.txt files here can be translated by creating a copy of the same file with a language suffix (e. g. db_bosch.txt => db_bosch-fr.txt).

Some mods may include briefing files here, and these files cannot be translated this way. You'll have to either overwrite the original file, or modify the custom briefing script to make the content internationalized (check the French translation of Solaris to see an example).

Movies

Here you can add subtitles to cutscenes by creating a *.srt file with the name of the video with language suffix (e. g. colossus.mp4 => colossus-fr.srt).

Subtitle Edit (https://www.nikse.dk/subtitleedit) is a good user-friendly tool to create your subtitles.

If you want to use a distinct font for movie subtitles, create a new one in fonts.tbl, and in game_settings.tbl or any *-mod.tbm file, add the $Movie Subtitle Font property (in the following example, 'Movie' is the name of the new font):

#OTHER SETTINGS
	$Movie Subtitle Font: Movie

#END

HUD and interface

Some mods use custom interfaces, with images containing text. You will need some basic image editing skill to translate them. Beware that these files are not internationalized, so you will have to overwrite the original files!

Maps

In some mods you can find *.dds files which contain nameplates for terran ships. You will need some basic image editing skill to translate them. Beware that these files are not internationalized, so you will have to overwrite the original files!

Tables

The following files are the most important, as they contain most of the text displayed in the game:

strings.tbl, and all files with the *-lcl.tbm pattern (these contain all the menu strings) tstrings.tbl and all files with the *-tlc.tbm pattern (these contain the mod content strings, so all missions, ship and weapon descriptions, credits...)

They can be translated by adding a new section with the name of your language copying inside all the original XSTR entries replaced with your new translation.

Example of an original strings.tbl:

#Default

0, "Player ship changed to %s"

#End

Example of a translated strings.tbl:

#Default

0, "Player ship changed to %s"
;the rest of the strings

#End

#French

0, "Vaisseau du joueur à présent %s"
;the rest of the strings

#End

The number at the beginning of each row must stay the same between languages, as it is the ID used by the game to look for the matching string.

Note that the new translated section can also be placed in a distinct *-lcl.tbm/*-tlc.tbm file if you are familiar enough with modular tables.

Some variables can be used inside the strings for special uses. These are the most useful but there are probably more:

• $quote: replaces the " character, as it is already used by the table format to recognize the string
• $rank: this will be replaced by the current rank of the player ($Alt Name property in rank.tbl)
• $rtitle: similar to $rank, but can be used in case your language uses different names for the same rank depending on the context ($Title property in rank.tbl)

Voices

Contains all the voice acting files, if you are extremely motivated. Beware that these files are not internationalized, so you will have to overwrite the original files!

Updating your existing translation

Let's say you previously translated the v1 of a mod, and now you want to translate v2 but you are not sure what strings changed or were added between both versions.

For this case, I developed a tool you can use: https://codeberg.org/AchilleParmentier/FreeSpace2TranslationTools/releases. In the second tab 'Update translations' of this tool, you can automatically transfer all unchanged texts from your translated v1 to your new translated v2 file (even if they don't have the same ID anymore). Then you will only have to translate the new and modified strings.

Related Links

Discussion thread | Hard-Light Productions