LANGUAGE

From ZDoom Wiki
Jump to navigation Jump to search

The LANGUAGE lump allows modders to define placeholder keywords and their string translation in several languages. As of GZDoom 4.0.0, there are two varieties of LANGUAGE lump: A .csv spreadsheet exported from Google Docs containing strings for multiple languages, or the old-style plaintext format, which typically holds only one language at a time with multiple LANGUAGE lumps present. LANGUAGE lumps, like all other text lumps, are cumulative and allow both types of C-style comments.

A LANGUAGE lump is a series of sections containing associations between a keyword (usually in ALLCAPS) and a string (between quote marks), ended with a semicolon. A section begins by a header containing the appropriate language codes between square brackets (several language codes can be contained in the same header) and continues until the next section header is encountered.

This wiki page primarily concerns the old-style format, which modders are still encouraged to use. For more information on the official translation spreadsheet, see internationalization.

Language codes

  • default: The fallback used if no translation in the user's language is available, or if the user's language is unknown. If the default isn't available either, the keyword will be displayed directly.
  • enu: English (US)
  • eng: English (UK)
  • cs: Česky (Czech)
  • de: Deutsch (German)
  • es: Español (España) (Castilian Spanish)
  • esm: Español (Latino) (Latin American Spanish)
  • eo: Esperanto
  • fi: Suomi (Finnish)
  • fr: Français (French)
  • hu: Magyar (Hungarian)
  • it: Italiano (Italian)
  • jp: 日本語 (Japanese)
  • ko: 한국어 (Korean)
  • nl: Nederlands (Dutch)
  • pl: Polski (Polish)
  • ptg: Português (European Portuguese)
  • pt: Português do Brasil (Brazilian Portuguese)
  • ro: Română (Romanian)
  • ru: Русский (Russian)
  • sr: Српски (Serbian)


Keep in mind that for some of these languages, providing new fonts may be required as the default fonts in Doom, Heretic, Hexen and Strife do not cover accented characters or non-Latin characters.

Additional functionality

Strings defined in this lump supports some of Print's escape sequences, such as color (\c) and new line (\n).

Strings can also be split into multiple lines. In order for the strings to be split up in game, the new line escape character must be used. Otherwise, they will simply be merged together as one.

SPLIT_STRING =
	"This string is split into\n" // NO COMMAS AFTER THE DOUBLE QUOTATIONS.
	"multiple lines by the\n"
	"new line escape character.\n"; // Strings are all terminated with a semicolon.

NONSPLIT_STRING =
	"This string, on the other hand "
	"is NOT split up because the "
	"new line escape characters "
	"are not used. ";

A string can also be defined to point to another LANGUAGE string label (not necessarily within the same lump). This can be useful to avoid duplication:

MY_STRING_1 = "String 1 or 2";
MY_STRING_2 = "$$MY_STRING_1"; // MY_STRING_2 will also resolve to "String 1 or 2"

You can define a string only for a specific game by prefixing it with $ifgame(gamename), where 'gamename' can be any of 'doom', 'heretic', 'hexen', 'strife' or 'chex':

GAME_STRING = "This will be the text for any game";
$ifgame(heretic) GAME_STRING = "This will be the text for heretic";

Using the CSV format

Using a .csv file for the LANGUAGE lump is highly recommended over the old plaintext format. With a CSV you get a clean and clear structure, where localized versions of each string are positioned right next to each other, and the languages are separated by columns. A file like this can be easily viewed and localized, or uploaded into specialized translation software.

The LANGUAGE.csv file must adhere to the following requirements:

  • Delimiter: comma
  • Encoding: UTF-8
  • First line (column headers): language codes, as specified above.

Note: CSV cells support real linebreaks (usually created with a shortcut like Ctrl-Enter) instead of \n.

A CSV file can be created with [Google Sheets]: simply create a sheet with the proper structure, then choose File > Download > Comma-separated values (.csv, current sheet), then rename the downloaded file to LANGUAGE.csv and put it in your project's folder. Using a Google Sheet is also an easy way to set up collaboration between multiple translators.

Other software that can open and edit a CSV file will also work (such as MS Excel, LibreOffice, etc.). A CSV file can also be viewed as a plain text file with apps like Notepad++, but it's not recommended to edit it this way, since it's very cumbersome.

In ACS

Strings defined in LANGUAGE can be retrieved in ACS in functions that use string such as Print and HudMessage. With the letter 'l' specifier you can retrieve strings defined in LANGUAGE.

e.g.: Print(l:"ALARMWARN");

In DECORATE or MENUDEF

Strings defined in LANGUAGE can be retrieved in DECORATE by prefixing their keyword with the $ sign and putting it between quote marks. If ZDoom doesn't find any string for this keyword in the user's language's section, it will look for a match in the default section. If there is no match there either, the keyword will be displayed directly.

e.g.: Obituary "$OB_MYMONSTER"

In ZScript

ZScript strings will not automatically resolve to the desired definition in LANGUAGE. However, getting the string is simple. This example gets the defined QUITMSG string. If the string isn't found, it will simply return $QUITMSG.

e.g.:String quitmessage = Stringtable.Localize("$QUITMSG");

In MAPINFO

Strings defined in LANGUAGE can be retrieved in two different ways in MAPINFO. A name value without space and prefixed with a $ sign will be interpreted as a keyword. Alternatively, the lookup value can be used to directly indicate a keyword. If lookup is used, then the keyword should not be within quotes.

e.g.:map MYMAP lookup HUSTR_MYMAP
map MYMAP name "$HUSTR_MYMAP"

Compare with map MYMAP "My map".

In SECRETS

Strings defined in LANGUAGE can be retrieved for the hint text of a secret entry by prefixing its keyword with the $ sign.

e.g.: $s36;$SECRETHINT_AMMOCACHE

Obituary assignment

LANGUAGE can be used to assign obituaries to actors. There are generic and damage-type-specific obituaries. The syntax is as follows:

Obituary_<classname> = "<obituarytext>";
Obituary_<classname>_<damagetype> = "<obituarytext>";

classname is the class name of the actor, while damagetype is the MOD (means of death). This is for damage-type-specific obituaries.

The advantage of this method is that it can be used to easily assign obituaries to actors that originally had none, without the need to create modified versions to replace the originals with. It is also the only way to assign damage-type-specific obituaries.

Note that this method of assigning obituaries takes precedence over the obituary actor properties.

Example

This assigns the imp a new set of obituaries.

Obituary_DoomImp = "%o was turned to ashes by an imp's fireball.";
Obituary_DoomImp_Melee = "%o got clawed in the face by an imp.";

Example

// This is an example LANGUAGE LUMP

[enu default] 
/* This section is both for American English (enu -> en US) and the default language
   (used if there are no available translations for the user's own language).        */

S_SUPERWEAPON = "Picked up the ultimate superweapon!";
NEEDMAUVEKEYD = "You need a mauve key to open this door.";
NEEDMAUVEKEYO = "You need a mauve key to activate this object.";

[fr]
/* And now a French translation for the above lines */

S_SUPERWEAPON = "La super-arme ultime !";
NEEDMAUVEKEYD = "Il vous faut la clef mauve pour ouvrir cette porte.";
NEEDMAUVEKEYO = "Il vous faut la clef mauve pour actionner cet objet.";

[de]
/* In German, too */
S_SUPERWEAPON = "Die maximale Überwaffe !";
// Oh no, what about the mauve key messages? They don't have a translation!
// Then they'll just use the English versions above since they're also defined as being the default.


See also