Cities Skylines translation tools.
----------------------------------



1. Introduction
---------------

Cities Skylines uses a proprietary file format for its language files. These
files are not human editable. Therefore, in order to translate the game into
more languages, tools are neccessary to create and edit these files.

The library ColossalManaged.dll, that is shipped with Cities Skylines,
contains support to read and write .locale files. The consequence is that
it is almost a necessity to write tools in C#.

This package contains tools that allow you to convert from and to language
files. The tools are command-line tools, that must be run from a Windows
Command prompt or Linux shellj. I dislike GUI utilities because they cannot
be automated.

Translating consists of several steps:
   1. Convert an existing .locale file into a .po (gettext) file
   2. Edit the .po file
   3. Create a new .locale file from the original file and the .po file


2. Getting started
------------------

Extract this zip file in a directory and copy ColossalManaged.dll, into it. This
file comes with Cities Skylines and can be found in its installation directory.
Linux users will also have to install Mono. Most distributions contain Mono,
you can use zypper, yum or apt-get to install, i.e.:

zypper install mono

Dependencies have been avoided, so just the basic Mono installation is
sufficient.

3. Convert an existing .locale file into a .po (gettext) file
-------------------------------------------------------------

This is done with the tool locale2po. Open a command prompt or Linux shell and
cd to the directory where you have the tools available.

An example to convert the English locale file is:

Linux users:
    mono locale2po.exe -input en.locale -output en.po
Windows users:
    locale2po -input en.locale -output en.po

After executing the command the file en.po has been created.


4. Edit the .po file
--------------------

.po files are the GNU gettext format. The gettext format is a very common file
format for translating software. .po files can be edited with any text editor.
If you want to do this, open the .po file in a text editor and add your
translations to the msgstr lines. You have to leave the #. lines and the msgid
lines unmodified).

However, there exists also a lot of software to edit .po files. It is
recommended to use such software, because you will be able to translated much
faster (yes, really).

For now the only tested program is Lokalize, which is part of the KDE software
packages (don't worry, there is a Windows version). Other tools may also work
but please understand that the tools do not support all features of the gettext
file format. With Lokalize, the game can be quickly translated.


5. Create a new .locale file from the original file and the .po file
--------------------------------------------------------------------

This is done with the tool locale2po. Open a command prompt or Linux shell and
cd to the directory where you have the tools available.

An example to convert a Dutch language .po into locale file is:

Linux users:
    mono po2locale.exe -original en.locale -po nl.po -output export.locale -nativename 'NEDERLANDS' -englishname '(DUTCH)'
Windows users:
    po2locale -original en.locale -po nl.po -output export.locale -nativename "NEDERLANDS" -englishname "(DUTCH)"

After executing the command the file export.po has been created. You can copy
this into the games' locale directory and then you can select the new language
in the game.

The po2locale tool supports a few command line options:

  -original		This used to specify the original .locale file that you
                          converted into .po with locale2po.
  -po			This used to specify the .po file that you have edited
  -output		This used to specify the name of the .locale file that
                          needs to be created
  -nativename		This is the name of the language of the new .locale
			  file, as it is called in that language itself
  -englishname		This is the name of the language of the new .locale
                          file, as it is called in the English language
  -version		This is the version of the .locale fileformat to use.
                          The current version seems to be 2, and this is
                          the default.


6. Creating a mod
-----------------

Unfortunately, there is no official way to publish your language file into the
workshop, just like you can with assets, maps, colour corrections and styles.
The only solutionis to clothe your language file as a mod. However, this
requires programming, increasing the amount of knowledge required to be able
to do it.

In the subdirectory Mod, you will find example files for creating a mod from
your language file. The following instructions assume a Linux system, because
I don't know how to do it on Windows.

The first step is to rename the file, for example if you are translating into
Bulgarian:

mv Mod_Lang_NL.cs Mod_Lang_BG.cs

Next step is to adjust the Makefile

Mod_Lang_NL.dll: Mod_Lang_NL.cs nl.locale
	mcs -target:library -r:ColossalManaged.dll -r:ICities.dll -r:Assembly-CSharp.dll -codepage:utf8 -resource:nl.locale,Mod_Lang_NL.nl.locale $<

... would become:

Mod_Lang_BG.dll: Mod_Lang_BG.cs bg.locale
	mcs -target:library -r:ColossalManaged.dll -r:ICities.dll -r:Assembly-CSharp.dll -codepage:utf8 -resource:bg.locale,Mod_Lang_BG.bg.locale $<

The next step is to adjust the Language codes at the start of the file:

namespace Mod_Lang_NL
{
	public class Mod_Lang_NL : IUserMod
	{
		private string locale_name = "nl";

... would become:

namespace Mod_Lang_BG
{
	public class Mod_Lang_BG : IUserMod
	{
		private string locale_name = "bg";


Now modify the mod names and descriptions at the bottom of the file, i.e.

                default:
                        return "Dutch localization Mod";

... would become:

                default:
                        return "Bulgarian localization Mod";

Copy the files Assembly-CSharp.dll  ColossalManaged.dll  ICities.dll from the
game directory to the mod source code dirrectory.

Type "make", and if everything goes well, you mod will now be created and you
can publish your mod on the Steam Workshop.

The mod source code was originally written by the authors of the Traditional
Chinese translation. Please give their mod a visit and give it a positive vote:

http://steamcommunity.com/sharedfiles/filedetails/?id=417564312

I have made some improvements to the source code:
* It only installs the language file if it does not yet already exist, or if
  the file size is not correct
* The activation mechanism is through the OnEnabled method, which is a lot less
  ugly than through the Name method. This also means users can disable the mod
  inside the content manager of the game
* It is multi-lingual itself and will display the mod name and description in
  multiple languages.
