NMLTutorial/Language files - Revision history

Hirogen2: write style

2012-10-13T17:41:21Z

write style

← Older revision		Revision as of 17:41, 13 October 2012
Line 1:		Line 1:
	{{NMLTutorial}}		{{NMLTutorial}}

	All texts (or ''strings'') you want or need to use in a NewGRF go into a language file. Each language has ~~it's~~ own language file, which makes translations in NML very easy.		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 ==		== Language folder structure ==
	Of course you want to keep all the source files for one NewGRF together in one ~~folder~~, right? In this ~~folder~~, create a ~~subfolder~~ with the name <code>lang</code>. This is the default ~~folder~~ name NML looks in for language files. You can use a different ~~folder~~ name if you want to, but then you need to teach NML ~~what~~ this ~~folder is~~.		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 <code>lang</code>. 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 ===		=== File extensions ===
Line 11:		Line 11:

	=== Default language ===		=== 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 ~~isn't~~ complete. The default default language is ''english.lng''. If that is fine with you, you ~~don't~~ have to make any other settings. If you want a different default language, you need to tell NML which one this is; see the [[NMLTutorial/Installation#NML_Commandline_Options\|installation page]] on which commandline option to supply to do this.		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 [[NMLTutorial/Installation#NML_Commandline_Options\|installation page]] on which commandline option to supply to do this.

	=== Example ~~folder~~ structure ===		=== Example directory structure ===
	As a result, your ~~folder~~ structure should look something like the following:		As a result, your directory structure should look something like the following:

	mygrf		mygrf
	\|- lang		\_ lang
	\| \|- english.lng		\| \_ english.lng
	\| \|- other_language.lng		\| \_ other_language.lng
	\|- mygrf.nml (which we~~'ll~~ create later)		\_ mygrf.nml (which we will create later)


Line 33:		Line 33:
	</pre>		</pre>

	<code><number></code> is the number of the language in this file. You can look these numbers up [http://newgrf-specs.tt-wiki.net/wiki/NML:Language_files here]. This number needs to be written as ~~''byte'',~~ ~~which~~ ~~means you have to precede it with~~ <code>0x</code>. For example, the language number for British English is 01, so as <code><number></code> you need to put <code>0x01</code>. Dutch has 1F as language number, so in case of dutch.lng you put <code>0x1F</code>.		<code><number></code> is the number of the language in this file. You can look these numbers up [http://newgrf-specs.tt-wiki.net/wiki/NML:Language_files here]. This number needs to be written with the hexadecimal prefix <code>0x</code>. For example, the language number for British English is 01, so as <code><number></code> you need to put <code>0x01</code>. Dutch has 1F as language number, so in case of <code>dutch.lng</code>, you put <code>0x1F</code>.

	=== String names ===		=== String names ===
	Each piece of text, a string, needs to have a unique <code><string-name></code>. 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 ~~don't~~ get duplicates with other names you~~'ll~~ be using in your NML file and the captitals make the code a little bit easier to read.		Each piece of text, a string, needs to have a unique <code><string-name></code>. 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.		Every new string name will start on a new line in the language file.
Line 44:		Line 44:

	=== String codes ===		=== 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 [http://wiki.openttd.org/Strings 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~~'ll~~ just have to try and see.		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 [http://wiki.openttd.org/Strings 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 ===		=== ASCII or Unicode ===
	When saving the language file, you should pay a little attention to the character encoding you use. If you only use ~~LATIN~~-1 characters in your language file, you can save as both ASCII and ~~Unicode (=~~UTF-8). If you use non-~~latin~~ characters, such as for Cyrillic, Arabic or Asian languages, you must save as ~~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 ===		=== Comments in language files ===
Line 71:		Line 71:

	== Custom string codes ==		== Custom string codes ==
	For things such as a version number it's useful to define a custom string code. That way you ~~don't~~ 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.		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 <code>custom_tags.txt</code> which resides outside the lang ~~folder~~, next to your nml file:		Custom string codes go in a file called <code>custom_tags.txt</code> which resides outside the ''lang'' directory, next to your nml file:

	mygrf		mygrf
	\|- lang		\_ lang
	\| \|- english.lng		\| \_ english.lng
	\| \|- other_language.lng		\| \_ other_language.lng
	\|- custom_tags.txt		\_ custom_tags.txt
	\|- mygrf.nml		\_ mygrf.nml

	The format of <code>custom_tags.txt</code> is similar to a language file, but ~~doesn't~~ have the <code>##grflangid</code> definition, for example:		The format of <code>custom_tags.txt</code> is similar to a language file, but does not have the <code>##grflangid</code> definition, for example:

	<pre style="color:darkblue">		<pre style="color:darkblue">
Line 89:		Line 89:
	</pre>		</pre>

	The same rules for character encoding apply and once you have this you can change your language file into something like the following:		The same rules for character encoding apply, and once you have this, you can change your language file into something like the following:

	<pre style="color:darkblue">		<pre style="color:darkblue">
Line 119:		Line 119:
	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 <code>custom_tags.txt</code> where it is useful.		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 <code>custom_tags.txt</code> where it is useful.

	Got that? Great! Now there's only one step left before you are going to create your actual NML file!		Got that? Great! Now there is only one step left before you are going to create your actual NML file!

	{{NMLTutorialNavbar\|Graphic files\|NML Syntax}}		{{NMLTutorialNavbar\|Graphic files\|NML Syntax}}

FooBar: pre class

2011-08-27T22:20:40Z

pre class

← Older revision		Revision as of 22:20, 27 August 2011
Line 26:		Line 26:
	The contents of each language file itself has the following structure:		The contents of each language file itself has the following structure:

			<pre class="pseudo">
	~~<pre>~~##grflangid <number>		##grflangid <number>
	<string-name> :<text>		<string-name> :<text>
	<string-name> :<text>		<string-name> :<text>

FooBar: how to create NML language files

2011-08-22T13:59:12Z

how to create NML language files

New page

{{NMLTutorial}}

All texts (or ''strings'') you want or need to use in a NewGRF go into a language file. Each language has it's 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 folder, right? In this folder, create a subfolder with the name <code>lang</code>. This is the default folder name NML looks in for language files. You can use a different folder name if you want to, but then you need to teach NML what this folder is.

=== File extensions ===
Every language file needs to have the <code>.lng</code> 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 isn't complete. The default default language is ''english.lng''. If that is fine with you, you don't have to make any other settings. If you want a different default language, you need to tell NML which one this is; see the [[NMLTutorial/Installation#NML_Commandline_Options|installation page]] on which commandline option to supply to do this.

=== Example folder structure ===
As a result, your folder structure should look something like the following:

mygrf
|- lang
| |- english.lng
| |- other_language.lng
|- mygrf.nml (which we'll create later)

== Language file structure ==
The contents of each language file itself has the following structure:

<pre>##grflangid <number>
<string-name> :<text>
<string-name> :<text>
...
</pre>

<code><number></code> is the number of the language in this file. You can look these numbers up [http://newgrf-specs.tt-wiki.net/wiki/NML:Language_files here]. This number needs to be written as ''byte'', which means you have to precede it with <code>0x</code>. For example, the language number for British English is 01, so as <code><number></code> you need to put <code>0x01</code>. Dutch has 1F as language number, so in case of dutch.lng you put <code>0x1F</code>.

=== String names ===
Each piece of text, a string, needs to have a unique <code><string-name></code>. 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 don't get duplicates with other names you'll 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 [http://wiki.openttd.org/Strings 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'll 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 LATIN-1 characters in your language file, you can save as both ASCII and Unicode (=UTF-8). If you use non-latin characters, such as for Cyrillic, Arabic or Asian languages, you must save as Unicode.

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

<pre style="color:darkblue">
##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
</pre>

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's useful to define a custom string code. That way you don't 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 <code>custom_tags.txt</code> which resides outside the lang folder, next to your nml file:

mygrf
|- lang
| |- english.lng
| |- other_language.lng
|- custom_tags.txt
|- mygrf.nml

The format of <code>custom_tags.txt</code> is similar to a language file, but doesn't have the <code>##grflangid</code> definition, for example:

<pre style="color:darkblue">
VERSION :0.1.0
TITLE :My GRF
</pre>

The same rules for character encoding apply and once you have this you can change your language file into something like the following:

<pre style="color:darkblue">
##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
</pre>

The Dutch language file for example then can use these same custom sting codes:

<pre style="color:darkblue">
##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.
</pre>

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 <code>custom_tags.txt</code> where it is useful.

Got that? Great! Now there's only one step left before you are going to create your actual NML file!

{{NMLTutorialNavbar|Graphic files|NML Syntax}}