ttm mkxp translation doc

Translation mechanism for "To the Moon" on mkxp
=================================================================

The mechanism is split up into logical parts which mostly stand on their own. The data used as basis for this are already fully translated game files for each language. This mechanism does NOT deal with the translation process itself, it only harvests the finished data and packs it efficiently. It also does not deal with maintaining existing translations.
I will refer to the original language the game was written in (English) as the "source language", and the translated language as "target language".

<lang_code> refers to the [IETF language tag](http://en.wikipedia.org/wiki/IETF_language_tag) of the target language.

Events
------
A "command list" is an array of RPG::EventCommand objects. Every EventCommand encapsulates one "instruction", which are executed by the "Interpreter" part of the game scripts. For the most part, there are two kinds of translatable commands inside command lists, text messages and choice branches.
Text messages are split up into commands of code 101 (`TEXT`, beginning of tex box) and 401 (`TEXTC`, continuation of text box), each holding one line of text. These commands are grouped into "text blocks", which are all text commands surrounded by non-text commands. Blocks are the fundamental text unit, and no regard is paid to their actual size, since the line count of the source text doesn't necessarily have to match the target one.
All text blocks of a target language found in one command list are collected (`text_data`) and only identified by the order of their appearance.

Example of text blocks in a command list:

    MOVEV  [17, #<RPG::MoveRoute>]
    MOVEVC [#<RPG::MoveCommand>]
    TEXT   ["\ignr\e[17]\nm[ Dr. Watts ]"]           | text block
    TEXTC  [""That's okay, \.I tend to be bad at"]   |
    TEXTC  ["predicting deaths as well.""]           |
    MOVEV  [17, #<RPG::MoveRoute>]
    MOVEVC [#<RPG::MoveCommand>]
    MOVEV  [-1, #<RPG::MoveRoute>]
    WAIT   [3]
    TEXT   ["\ignr\e[18]\nm[ Dr. Rosalene ]"]        | text block
    TEXTC  [""Are you the patient's daughter?""]     |
    TEXT   ["\ignr\e[16]\nm[ Lily ]"]                |
    TEXTC  [""Oh no, \.I am just his caretaker."  "] |
    MOVEV  [-1, #<RPG::MoveRoute>]

Choice branches are made up of the commands 102 (`CHOICE`, beginning of choice block, contains a list of possible choices), 402 (`CHOCIF`, 'if' beginning of a single choice branch), 403 (`CHOCEL`, 'else' beginning of the branch taken when the choice is canceled) and 404 (`CHOCEND`, end of choice block). Since `CHOCEL` and `CHOCEND` don't contain any translatable text, they're ignored. For a given page command list, all `CHOICE` and `CHOCIF` commands of a target language are collected (`choice_data`) and only identified by the order of their appearance.

Example of choice commands in a command list:

    TEXT    ["Choose a color!"]
    CHOICE  [["Red", "Green"], 5]             | collected
    CHOCIF  [0, "Red"]                        | collected
      TEXT  ["You chose red!"]
      END   []
    CHOCIF  [1, "Green"]                      | collected
      TEXT  ["You chose green!"]
      END   []
    CHOCEL  []
      TEXT  ["You didn't choose anything.."]
      END   []
    CHOCEND []
    TEXT    ["See you!"]
    END     []

In the rare case that a command list in the target language is structurally incompatible with the source (eg. additional nested branches), the entire command list is collected (`substitute`).

These three pieces of data describe one translated command list (`list_data`). Refer to "lang_data.spec" for the specific data layout.

When patching a command list (replacing the source with target language text), if no substitute data exists, all text blocks and choice commands are replaced with those of the target language data. No checking is done if choice command codes match up, it is assumed that source and target are structurally identical. If substitute data does exist, the entire command list is replaced with it instead.

A map contains a hash of events. An event contains an array of pages. A page carries one command list each. When a map is loaded by the game (due to player transfer), it still contains the source language text. All events are traversed and their page comannd lists are patched (if data is available).

Common Events
-------------
Common Events are treated the same as map events, except that they contain just one command list each. All common events are patched when language data is loaded.

Items
-----
The global array of RPG::Item objects ($data_items) is replaced with the target language's one when language data is loaded.

Meta
----
This refers to all kinds of strings and other data (like text sizes) found in the script database unique to a language. Contained in one hash, they are accessed via symbol keys. If a value is not defined for the target language, the source language value is used as default fallback.
Because this data is needed by the language choice scene, it is stored in the file "meta.rxdata" separately from lang_data.

Image files
-------
When a bitmap is loaded from an image file, the file name is checked against a set of known translatable image files. If it is translatable, the game will first try to load it from "lang/<lang_code>/", and fallback to "./".

Therefore, the file structure for each language looks like this:

lang/
|-- index.rxdata
|-- <lang_code>/
   |-- lang.rxdata
   |-- meta.rxdata
   |-- Graphics/
      |-- Animations/
      |-- Characters/
      |-- (etc..)

"index.rxdata" is a marshalled array of all valid <lang_code>'s.