NMLTutorial/Language files
All texts (or strings) you want or need to use in a NewGRF go into a language file. Each language has its own language file, which makes translations in NML very easy.
Language folder structure
Of course you want to keep all the source files for one NewGRF together in one directory, right? In this directory, create a subdirectory with the name lang. This is the default directory name NML looks in for language files. You can use a different name if you want to, but then you need to teach NML this name.
File extensions
Every language file needs to have the .lng file extension, otherwise NML will not recognise them.
Default language
You need to have exactly one default language for your NewGRF project. This language will be used if the user selects a language not available in the NewGRF, or if some translation is not complete. The default default language is english.lng. If that is fine with you, you do not have to make any other settings. If you want a different default language, you need to tell NML which one this is; see the installation page on which commandline option to supply to do this.
Example directory structure
As a result, your directory structure should look something like the following:
mygrf \_ lang | \_ english.lng | \_ other_language.lng \_ mygrf.nml (which we will create later)
Language file structure
The contents of each language file itself has the following structure:
##grflangid <number> <string-name> :<text> <string-name> :<text> ...
<number> is the number of the language in this file. You can look these numbers up here. This number needs to be written with the hexadecimal prefix 0x. For example, the language number for British English is 01, so as <number> you need to put 0x01. Dutch has 1F as language number, so in case of dutch.lng, you put 0x1F.
String names
Each piece of text, a string, needs to have a unique <string-name>. For this, you can choose whatever you want, but it is common practice to start each string name with STR_ and write it completely in capitals. That way, you do not get duplicates with other names you will be using in your NML file, and the captitals make the code a little bit easier to read.
Every new string name will start on a new line in the language file.
Texts
The text, or strings, themselves are written directly behind the string name, both completely on a single line. The string name and the string are separated by a colon. If you want to align the strings, you can do that by adding spaces of tabs in front of the colon. If you add them behind the colon, this whitespace will be part of the string!
String codes
You can use some special string codes inside strings, for instance, to instruct the game to continue the string on a new line, to use colours in your string, or to do some special things with strings. The formatting for these string codes is the same as used by OpenTTD. However, not all string codes are available in all locations where strings are displayed. Colours and special characters are generally available anywhere; other things you will just have to try and see.
ASCII or Unicode
When saving the language file, you should pay a little attention to the character encoding you use. If you only use ISO8859-1 or -15 (Latin-1/-15) characters in your language file, you can save as both ASCII and UTF-8 (one of many Unicode encodings). If you use non-Latin characters, such as for Cyrillic, Arabic or Asian languages, you must save as UTF-8.
Comments in language files
If you want to add comments in language files to make some notes in it that are not string definitions, start the line with the comment with a hash tag (#). Then you can write anything you want on that line and it will not be interpreted by NML.
Example language file
An example english.lng could contain the following:
##grflangid 0x01
# This is the English language file
# GRF name and description definitions
STR_GRF_NAME :My GRF 0.1.0
STR_GRF_DESCRIPTION :My GRF is the best there is and makes all other grfs obsolete!{}{COPYRIGHT}2011 Derp{}License: GPL v2
# vehicle names
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
Note the string codes for a new line {} and the copyright symbol in the GRF description.
Custom string codes
For things such as a version number, it is useful to define a custom string code. That way, you do not have to go and update the version number in every language file whenever you make a new release. You can also use it for the GRF title and basically anything you want, but these are the most useful applications.
Custom string codes go in a file called custom_tags.txt which resides outside the lang directory, next to your nml file:
mygrf \_ lang | \_ english.lng | \_ other_language.lng \_ custom_tags.txt \_ mygrf.nml
The format of custom_tags.txt is similar to a language file, but does not have the ##grflangid definition, for example:
VERSION :0.1.0 TITLE :My GRF
The same rules for character encoding apply, and once you have this, you can change your language file into something like the following:
##grflangid 0x01
# This is the English language file
# GRF name and description definitions
STR_GRF_NAME :{TITLE} {VERSION}
STR_GRF_DESCRIPTION :{TITLE} is the best there is and makes all other grfs obsolete!{}{COPYRIGHT}2011 Derp{}License: GPL v2
# vehicle names
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
The Dutch language file for example then can use these same custom sting codes:
##grflangid 0x1F
# This is the Dutch language file
# GRF name and description definitions
STR_GRF_NAME :{TITLE} {VERSION} - Mijn GRF
STR_GRF_DESCRIPTION :Mijn GRF is de beste die er is en maakt alle andere grfs overbodig!{}{COPYRIGHT}2011 Derp{}Licentie: GPL v2
# we will use the English vehicle name as well for Dutch, and don't re-define it here.
Now you know how to create language files, where they need to go and what you should put into them. Go ahead and create the default (English) language file and a language file for your own language (if English is your own language, then stick with the one default file). Add a name and description for the NewGRF you want to make and use custom_tags.txt where it is useful.
Got that? Great! Now there is only one step left before you are going to create your actual NML file!
NML Tutorial: Language files
