\documentclass[a4paper,12pt]{report}
\usepackage{gensymb}
%% \usepackage{babel}
\usepackage[latin1]{inputenc}
\begin{document}

\tableofcontents

\chapter{Translation}

\section{Introduction}

All texts of the game presented to the user are stored in separate data
files. No text is hard-coded. These texts are distributed over many
places for some reasons we will discuss later.

The game manages one variable that tells which language to use. So you
can switch between various languages by just changing that index
variable. There is no real limit for the number of languages.

Beside the problem to find every place where texts are encoded,
translating \emph{Danger from the Deep} to other languages is a straight
forward and simple process. At the moment one needs to change some code
in the main program to make newer languages available in the language
selection menu, but this can (and will) be done better in the future.
The game would just look for available languages in its data files and
present a selection by itself.

\section{Character encoding}

There are many possible characters that can be used in languages. To
make them all useable, the only choice is to use \emph{Unicode}
character encoding. Older games used 256 character together with a
code-table for various languages, but that is very clumsy. \emph{Danger
  from the Deep} uses the \emph{UTF-8} character encoding, which is a
special form to store 8-bit character texts (most compatible), but
encode within them characters up to 16 bits or more. This is done by
coding characters with Unicode number greater than 127 as multibyte
characters.

Don't worry when reading this, as your editor will handle all the nasty
details. Use a Unicode-compatible editor to read and write text files
(OpenOffice, any modern Unix or Windows editor etc.). Note that UTF-8
has become the defacto standard in the Linux world.

Beside encoding, the game must provide rendered bitmaps for each
character. At the moment we only provide characters within the 0\ldots
255 range of Unicode. This range is identical with the 256 characters of
the \emph{ISO-8859-1} code table, which contains characters for central
and west european languages. To support other languages from eastern
europe or even asian languages we would need to add new bitmaps for
those characters. This is planned, at least for east european languages
(ISO-8859-2 or ISO-8859-3, conforming to Unicode range 256\ldots511 or
until 767), but not done yet.

\section{Storage of the text resources}

The main texts are stored in \emph{csv} (``comma separates values'')
files. That is a human readable, simple text file format that can store
tables. Each column is separated by a semicolon to its neighbour. Lines
of the table are lines in the text file. Texts are embraced in double
quotes, as usual.

It is \emph{strongly} suggested to use a tool that can read, handle and
write such files. The best tool for it is \emph{OpenOffice}. Select
appropriate values when opening or saving the file (UTF-8 encoding,
semicolon as separators).

The files are stored in \texttt{dangerdeep/data/texts/}. There are at
the moment two \emph{csv} files, \texttt{common.csv} and
\texttt{languages.csv}. The \texttt{common.csv} file stores the main
texts while the \texttt{languages.csv} file stores language descriptions
for each language in each language.

The first line of a table is the headline, that contains the language
code for each column. The first column contains the number of the text
resource, one resource per line. This is very simple, just open a file
in OpenOffice and see yourself.

There are more places where texts are stored. Each object of the game
(ship, submarine, torpedo, airplane etc.) and each mission has its own
text resources. It would be difficult to store them centrally, because
when new ships are added, new resource lines would need to get
allocated. We could use a new \emph{csv} file for all object resources.
It is planned to regroup the data, so all files of a ship are stored in
one subdirectory. It would make sense to store the ship related texts
there as well and not in a central \emph{csv} file.

So as translator you have to browse the data description files (stored
as subdirectories of \texttt{dangerdeep/data/}, subdirectories
\texttt{ships/}, \texttt{submarines/}, \texttt{airplanes/},
\texttt{torpedoes/}, etc.) and look for some language related XML tags
within them (these files are XML files).  Each tag has a language code
attribute and the text itself. We know that this is the harder part of
the translation process as it is clumsy to locate each data file and
look for the text. Maybe the texts are reorganized in the future.

\section{Adding new languages}

To add a new language to \emph{Danger from the Deep} you have to add new
columns to the existing \emph{csv} files that contain the texts for that
language. You have to choose a language code as well. And you must add a
line in the \texttt{languages.csv} file for your language that contains
the name of the language in all available languages.

The more difficult part, as decribed above, is to localize the data
description XML files and their language related tags in them. You have
to add tags for your language as well. You have to do the same for the
missions. The best thing is to just open some files and have a look at
them, you can see how it works by the way the current four languages are
implemented.

If you find texts that are in English, but should be in another
language, then its most probable that this text resource has been added
recently, so the translator of that certain language hasn't updated the
file yet.

Note that \emph{Danger from the Deep} is constantly growing and thus new
resources are added periodically. So you need check for changes
sometimes and translate the new texts.

\section{Specials}

Languages have some other differences as well. Like the format of the
date and time. We should handle it that way, that a date and time format
string is stored as text resource, to make it easily changeable. But
this is not implemented yet, so all languages use the english format or
the german format for german language (the two original languages of the
game).

\section{Available translations}

At the time of this writing, there are four available languages:
English, German, Italian and Spanish. More languages are planned or
people are working on it. Requests are pending for: Polish, Russian,
French, Dutch.


\end{document}
