Gyakuten Saiban 3 translation guidelines

November 2005, Broco (broco@users.sourceforge.net)
http://comebackcourt.sourceforge.net/
v0.2

Contents


1 Introduction


1.1 Welcome!

Thanks for taking an interest in translating Gyakuten Saiban! There is a whopping 1.7 meg of uncompressed text in the script of Gyakuten Saiban 3, so any and all help is appreciated :). I'm Broco, ROM hacker and coordinator of the project.

As you can see from the preview release, the bulk of the ROM hacking has been done already. What's really needed now is translators, preferably some with lots of free time (although I'll take anything really :). Despite all the progress that's been done so far, this game will never be translated unless some dedicated translators join the team, so don't let my months of ROM hacking work go to waste: send me an email to join now!

I'm taking organization seriously for this project --- I used to be a translator in an earlier fan translation project that fell apart before release due to bad coordination, and I learned some lessons about how to avoid this happening again. Here the ROM is already thoroughly hacked before translation even begins, the tools are open-source, and we'll be making a lot of partial releases as we go. So I'm doing everything I can to make sure your translation efforts will not go to waste --- they'll make it into an actual release.

I am hoping that many translators will be interested in joining the team, so instead of explaining how everything works by email to each person individually, I thought I'd write a brief document explaining what's what once and for all. This text should hopefully cover everything you need to know to begin pumping out translated text and inserting it into the ROM.

The ROM hacking tools I wrote for Gyakuten Saiban are open-source and fairly user-friendly, so you won't need to send your translated blocks to me to have them inserted --- you'll be able to hack the ROM yourself and immediately look at your changes in-game as soon as you've got a few lines of the script translated. I'm hoping this will reduce post-translation editing work, as well as make the job more rewarding for the translators.


1.2 Quick start

I'm assuming you're running Windows. (If you're running Linux or Mac OS, please e-mail me and I'll port the stuff.) First download and unzip the source package onto your hard disk: it will create a directory called "cc3_source". Then take your copy of the Gyakuten Saiban 3 ROM (I'll call it "GS3.gba") and copy it into this directory. That's all the installation you should need to do.

My utilities are all command-line, so open a Windows command prompt and cd to the cc3_source directory. I've provided some Windows batch files to perform the most important operations on the ROM.

Run hackall GS3.gba to create a ROM that's fully translated up to the current stage of the distribution. It won't overwrite GS3.gba: it will make a new file called "CC3_English.gba". Start up a GBA emulator and try it out.

Run extractall GS3.gba to extract all the scripts (and a few other things) into the "extracted" directory. The human-readable text files are have the extension ".cc". Open one up with an SJIS-capable text editor to see how it looks. The file format is described in section 3.3 of this document.

Now take the script you want to translate (say case3-2.cc) and copy it into the root directory "cc3_source". Open it with a text editor and add the text "blah blah blah<p>" on the line right after the @PTR0 tag. Now run testhack case3-2.cc. This modifies the "CC3_English.gba" ROM to insert this script at the point where the beginning of Case 1 would normally be. So now if you start the hacked ROM and start Case 1 it will say "blah blah blah" in the bottom text box, and then go on to begin Case 3 Part 2. This should be helpful for testing how your translation looks. Now all you need to do is edit this .cc file to start translating.


2 Project coordination

It's important to keep in touch, and frequently send updates and partial translations to the team whenever any work gets done. My e-mail is broco@users.sourceforge.net; contact me and I'll allocate you some blocks to translate, and put you in touch with the other team members. If you would prefer to translate one case in particular, request to translate that case and there'll certainly be some of it available. Please don't start translating a block without sending an e-mail though, because we want to work efficiently and avoid having several translators do redundant work.

From now on, I (Broco) am planning to work on stuff relating to ROM hacking and project coordination, and leave the bulk of the translation to others (although if you want to take on other responsibilities, tell me and I'll be happy to take some off my shoulders :). Although my Japanese is quite good, translating that enormous amount of text is just overwhelming for one person, and it'll be lots of work for me just coordinating and inserting the translation that's done by others. (And I have the feeling that I'll end up translating quite a bit of the text anyway.) If you think you can help with the ROM hacking (extending the work to Gyakuten Saiban 1 and 2 in particular) drop me a line too, although that's much less needed.

For now e-mail will be adequate for communication. If enough people join the team, I'll also set up a private bulletin board and CVS server.


3 Technical info


3.1 General overview

There are several places in the Gyakuten Saiban 3 ROM that need to be modified in order to translate it.

By far the largest and most important is the script. The script contains all the text that appears in the box at the bottom of the screen. It also contains many control codes intermingled with the text: these codes basically regulate the entire flow of the game, adjusting backgrounds, sprites, sound effects, waits, etc. We'll need to replace all the Japanese text in the script with English text. Also, we'll need to make adjustments to many of the control codes to cope with the differing length and flow of English text. In the ROM, the script is stored in a compact binary form, but I've written a program to convert between this and an HTML-style human-readable hypertext (.cc files). You'll be modifying these .cc files to translate the game. (The .cc format is described in section 3.3 of this document.)

Text is stored in some other forms: there are the evidence boxes, which are 160x64 pixel 3-color bitmaps which appear during the game when you press the R button. I've written a program to convert grayscale .BMP files into Gyakuten Saiban's internal format, so currently these have to be made with an image editing program like Photoshop. It would be possible write a program to auto-generate them from .txt files --- I'll do this if making the pictures by hand proves too much of a pain. The fonts used here are: BatangChe 10pt, #636363 for title, Arial 10pt, #cecece for body.

There are the graphics. I've figured out how to modify the menu/nametag graphics and some have already been translated with a tile editor --- we'll have to do all of them. I haven't yet taken the time to figure out how to deal with the primary background/foreground graphics of the game, but although this is not so important it will have to eventually be done at some later stage of the translation. The title screen is a background graphic and the case selection boxes are foreground graphics. Also, some crucial in-game text is stored as background graphics --- when you press the L button for details, that stuff is always stored as background graphics (detailed police reports, the burnt parchment in Case 5, etc). The 証言開始, 無罪, 有罪, 異議あり and 待った animations are also foreground graphics, but I'm thinking that since they look cool as it is and their meaning is clear from context, we should probably just leave them in Japanese.

There were also many technical issues that needed to be dealt with inside the ROM, notably figuring out the script/graphics compression and rewriting the font display routine. Note that the new font display routine is designed to coexist with the old one: that means that a hacked ROM is able to display both English and Japanese text without any problems (however, please don't intermingle them in the same textbox). The ROM hacking is mostly done at this point and translators shouldn't have to worry about it much. For a detailed and technical overview of the ROM hacking front, see ROM_hacking_notes.txt.


3.2 Overview of the files

Here are all the files provided in the source distribution:

Files:

Directories:


3.3 The .cc file format

The .cc file format is a human-readable representation of Gyakuten Saiban scripts, which can be generated from and converted to raw script dumps by my ccscript program. I've designed this file format to be as easy and fast to type for translators as possible (if you have any suggestions as to how it could be improved further, please tell me: this file format is not set in stone).


3.3.1 Summary

There are 4 basic types of objects in a .cc file, each of which map directly to some binary codes in the ROM. These are:

Various numbers appear throughout .cc files, in such things as pointers, control code arguments and the names of unidentified control codes. Make sure to remember that all numbers are in hexadecimal (base 16). This is the number system that goes 0,1,2,3,4,5,6,7,8,9,A,B,C,D,E,F,10 instead of 0,1,2,3,4,5,6,7,8,9,10. This has the advantage of being more compact and faster to type, as well as more intuitive in many cases.

.cc files have a concept of whitespace. ASCII space characters, linebreaks, tabs, and comments (# This is a comment, terminated by a linebreak.) all count as whitespace. Whitespace will always be ignored completely except in one case: when it lies between two consecutive English characters (neither of which are space characters themselves). In that case, a single English space character will be inserted between those two English characters (always a single space character, regardless of the amount of whitespace). Note that since a raw script dumped from the original ROM will never contain a single English character, whitespace will always be ignored unless a file contains translated text.

.cc files begin with two directives: $NUMPOINTERS=xxxxxxxx, which gives the number of pointers found in total in this script, and (optionally) $MYSTERIOUSHEADER=xxxxxxxx, which is a mysterious number found in certain scripts whose purpose I haven't yet deciphered and which is best left untouched for now.

Finally, .cc files have certain translation aid features, namely [ ] autospacing boxes and the $TRANSLATED/$END_TRANSLATED directives, which are not strictly necessary but which you'll find extremely useful. See section 3.3.3 and 3.3.4 for how these work.


3.3.2 Control codes

The complete list of control codes, along with a description of each, is found at gs3_controlcodes.txt. I will describe only some of the most important ones here: please use that file for reference.

There are 128 possible control codes in total. I've figured out the function of only about a third of them, but in practice these are the most important ones that you'll see 95% of the time. Most control codes will be represented in .cc files in this form: <controlcodename arg1 arg2 arg3 arg4 ...>. The "controlcodename" can be either the raw number of the control code (a 2-character hexadecimal number from 00 to 7F) or a meaningful name I've given to it (such as color or testimony_box). Each control code takes a fixed number of arguments (parameters telling it what to do): these are all hexadecimal numbers. The number of arguments depends on the control code and can range from 0 to as much as 7. For example, color requires exactly one argument, telling it which color it should switch to.

Some of the most important and common control codes are represented in a shorthand form in ccscript. I came up with this shorthand because while translating text, I found that certain codes needed to be retyped over and over, and using the full HTML-style form was painful. Note that the full HTML-style form will still work for the following codes, though (if you really want to use it for some reason):

There are a few other important control codes which don't have a shorthand but which you should particularly know about.


3.3.3 [ ] boxes

As mentioned earlier, because the English font is variable-width it would be a nightmare to manually place all the <b> linebreak control codes. How can you figure out when a line ends? The primary goal of the [ ] autospacing boxes is to solve this for you. Each [ ] box should correspond to one textbox in the game, and ccscript will automatically take care of all the formatting within that box.

Auto-linebreaking. ccscript understands the width of each English character in Arial 13pt (which is what we use in the hacked ROM right now). When it sees a [ character, it starts calculating the width of the line starting from that point. When it realizes that a character just went past the right edge of the screen, it goes to find the last English space character that was inserted and replaces it with a <b> control code. If the next line after this also goes off the screen, then it outputs an error message: you've made this textbox too big and you'll have to remove some words or split it up into several. The count stops when it sees the ] character.

Note that ccscript also will detect <b> control codes that you've inserted manually and internally start counting from the second line when this happens. So if you want to force a linebreak inside a [ ] box for stylistic effect, you can still do so. In this case the only effect of the [ ] box (aside from the auto-spacing described below) will be to output an error if you go past the length of the second line.

Auto-spacing. Inserting linebreaks is their primary purpose, but the [ ] boxes also have a subtle but important effect on spacing. As I mentioned earlier, whitespace is always ignored except when it is found between two consecutive English characters, in which case a space character is inserted. This behavior is reasonable but it turns out to be actually too conservative in practice. For example, consider this typical text:

/3 Hello,/2=08 Naruhodo.=1a How are you *0today?

Here we have some speed, wait and shake control codes interspersed through the English text. But remember that whitespace is only significant when it's between two consecutive English characters. That means the control codes mess everything up here. What you'll find outputted in the game is: "Hello,Naruhodo.How are youtoday?". Bad, bad, bad.

So one obvious solution is to use underscores to force spaces where you want them, like this:

/3 Hello,/2=08_Naruhodo.=1a_How are you_*0today?

This will output "Hello, Naruhodo. How are you today?", correctly spaced as we want, but it's painful to type and it would be all too easy to forget to put these underscores all the time. So [ ] boxes also intelligently deal with this problem.

[/3 Hello,/2=08 Naruhodo.=1a How are you *0today?]

will put all the spaces at the right places. ccscript is intelligent enough to put spaces even when there are control codes between two characters, and it also understands that you should not put spaces before punctuation like periods and commas. The only place where [ ] autospacing regularly screws up is with quotation marks: you will need to put underscores before and after a quotation block if there are control codes before/after it.

There are only a few rare cases where [ ] boxes don't do what you want: in those cases, feel free to enter English text outside of a [ ] box, making sure to put the <b> at the right point. But in practice, 99% of your text should be in [ ] boxes.

If you look at a newly generated .cc file, you'll notice that ccscript automatically puts empty [] boxes after every line of Japanese. This is just to save you a little typing: you can write your English text inside the [ ] (and they have no effect on anything if you don't write any English inside the brackets). ccscript is smart enough to understand paragraph breaks and place the boxes accordingly, but if you're not happy with the autogenerated results you'll sometimes want to remove some brackets and merge lines to make things neater.


3.3.4 $TRANSLATED

While translating the script, one way of going about it would be to delete the original Japanese text and write the English text instead. But it strikes me that it would be better to leave the Japanese in alongside the English --- that way, it will be much easier to make revisions to the translation later without needing to constantly cross-reference an original dump of the script. We could simply "comment out" the Japanese instead of deleting it completely. That's why I came up with the $TRANSLATED directive. This directive tells ccscript to completely ignore any line coming after it that contains one or more Japanese (i.e. SJIS) characters. This behavior ends if the $END_TRANSLATED directive appears, after which Japanese text is inserted normally again.

Note that $TRANSLATED tells ccscript to ignore the entire line whenever it sees Japanese; that means any control codes on that line will be ignored too. Watch out that no important control codes are on a line with Japanese on it. Fortunately, ccscript is pretty smart and when it generates a new .cc file it will ensure that only the shorthand control codes and <b> are on the same line as Japanese text --- so in fact this this dangerous-sounding behavior is a good thing, because it will automatically kill all those control codes that you don't want in your translation anyway.


3.3.5 Examples

Let's look at some real examples of script and how to translate them. These examples are taken from the beginning of case1-1.cc, and they were used in generating the preview release.

First, an example of some basic text. Near the beginning of case1-1.cc, we find this text:

‥‥千尋クン。=10<b>とにかく、まずは落ちつくんぢゃ。
[]
<p>
そんなキョロキョロしとったら、<b>挙動不審でタイホされちまうぞ。
[]

Nothing special here, other than the =10 wait control code and a few linebreaks. I translated this as:

$TRANSLATED
‥‥千尋クン。=10<b>とにかく、まずは落ちつくんぢゃ。
[... Chihiro.=10<b>First of all, calm down.]
<p>
そんなキョロキョロしとったら、<b>挙動不審でタイホされちまうぞ。
[If you keep fidgeting, you'll be arrested for hyperactivity in court.]
$END_TRANSLATED

(In practice the $TRANSLATED and $END_TRANSLATED are far away from this point, not right beside, but just remember that they have to be there for the Japanese to be removed properly.) I inserted a linebreak in the translation of the first line for stylistic reasons, though it wasn't strictly necessary (in the second line, I let the brackets insert it). I had to take a few liberties with the translation in the second line to make it funny and fit within the box (it just barely fits), but that's all par for the course.

Here's a slightly more complex example, taken from the opening animation of case1-1 where Naruhodo appears to murder the victim:

<bgcolor 204 1 1f>=19<nextpage_nobutton><bganim 3 201><bg ff><bgcolor 100 0 1f>
=01*0<bgcolor 301 8 1f>
%0/1‥‥
[]
<sound 48 1><bgcolor 301 8 1f>
やめ
[]
<bgcolor 301 8 1f>
てくれッ!=64
[]
<nextpage_nobutton>
=0a/3彼女のコト/c‥‥=28<b>*1/2そんなふうに言うなッ!=50
[]
<bgcolor 301 8 1f><bgcolor 400 0 1f>=01<hidetextbox 1><nextpage_nobutton><bg ff>
<bgcolor 100 0 1f>=01<bganim 6 200><sound 16e 1>=24<bgcolor 400 0 1f>=01<bganim 6 201>
<bganim c 3><bg 37><bganim b 201><bganim 1 202><music 14f 0><bgcolor 304 1 1f>
=19=60=28<bganim 1 3>=50<6B 1 0 0><bganim c 200>=b4=b4<hidetextbox 0>

Now here we see there's lots of fancy control codes doing all sorts of gimmicks we don't understand with the music and animation. Don't worry about them: just leave them as they are and they should keep working in your translated version. All you need to do is fill in the brackets:

$TRANSLATED
<bgcolor 204 1 1f>=19<nextpage_nobutton><bganim 3 201><bg ff><bgcolor 100 0 1f>
=01*0<bgcolor 301 8 1f>
%0/1‥‥
[%0/1
<sound 48 1><bgcolor 301 8 1f>
やめ
Stop
<bgcolor 301 8 1f>
てくれッ!=64
it!=64]
<nextpage_nobutton>
=0a/3彼女のコト/c‥‥=28<b>*1/2そんなふうに言うなッ!=50
[=0a/2Stop it/c...=28*1/1stop bloody badmouthing her!=50]
<bgcolor 301 8 1f><bgcolor 400 0 1f>=01<hidetextbox 1><nextpage_nobutton><bg ff>
<bgcolor 100 0 1f>=01<bganim 6 200><sound 16e 1>=24<bgcolor 400 0 1f>=01<bganim 6 201>
<bganim c 3><bg 37><bganim b 201><bganim 1 202><music 14f 0><bgcolor 304 1 1f>
=19=60=28<bganim 1 3>=50<6B 1 0 0><bganim c 200>=b4=b4<hidetextbox 0>
$END_TRANSLATED

Now I decided to omit completely the opening ellipsis (....) completely, because it isn't used as much in English. Here ccscript wasn't so smart about where to split the lines and put the brackets, so I had to remove some of the brackets to make sure the first block represents an entire textbox. Note that even though "Stop it!" obviously takes no more than one line, the brackets still perform a useful function because they insert a space between the "Stop" and the "it". As for the second line, it's a pretty straight translation: you'll notice however that I increased the value of the speed control codes from /3 and /2 to /2 and /1 respectively.

Now let's take an example from few lines in the witness mode:

@PTR21

<noop><testimony_box ac 0><person a 0 0><bg 3><name 300><54 0 1><hidetextbox 0>
<person a 238 0>
%3カゼゴロシ・Zは、この2・3日<b>ずっと飲んでいたんですけど‥‥%0
[]
<special_jmp><endjmp>

@PTR22

<noop><testimony_box ad 0><person a 0 0><bg 3><name 300><54 0 1><hidetextbox 0>
<person a 238 0>
%3事件のあった日のおヒルごはんの<b>ときから、なくなっちゃって。%0
[]
<special_jmp><endjmp>

As you can see, each box has a pointer to it, which is used by the game to skip between them. Here it's crucial that your translation take up no more than one box; it would be a pain to have to add another one, with a new pointer and all. Other than that, though, it's a pretty straight translation:

$TRANSLATED
@PTR21

<noop><testimony_box ac 0><person a 0 0><bg 3><name 300><54 0 1><hidetextbox 0>
<person a 238 0>
%3カゼゴロシ・Zは、この2・3日<b>ずっと飲んでいたんですけど‥‥%0
[%3/2I had been taking Cold-Killer Z for two or three days straight...%0]
<special_jmp><endjmp>

@PTR22

<noop><testimony_box ad 0><person a 0 0><bg 3><name 300><54 0 1><hidetextbox 0>
<person a 238 0>
%3事件のあった日のおヒルごはんの<b>ときから、なくなっちゃって。%0
[%3/2But on the day of his death, it disappeared around lunchtime.%0]
<special_jmp><endjmp>
$END_TRANSLATED

Finally, here's one of the rare examples where using the [ ] brackets is not appropriate:

/5なるほどさん。=10あなた‥‥
[]
<wait_noanim 2d><b><26 1><person 25 148 0><bgtile 3><bg e><bgcolor 301 8 1f>
<sound 48 1>*1<sound 48 1>
/2この私に、=0cウソをついたのねっ!
[]
<nextpage_button><person 0 0 0><hideperson><26 0><person a 3e8 3e8><bg 3>
<name 300>
/6‥‥‥‥/8‥‥/a‥‥/c‥‥=46<b>
[]
<sound 4c 1>*2<bgcolor 301 8 1f><person a 1cb0 1cb0><bgcolor 301 8 1f>=05<sound 4c 1>
*2=05<bgcolor 301 8 1f>
/2ごめん
[]
<bgcolor 301 8 1f>
なさ
[]
<bgcolor 301 8 1f>
わわ
[]
<sound 4c 1>*2<bgcolor 301 8 1f>
ああああ
[]
<bgcolor 301 8 1f>
ああ
[]
<bgcolor 301 8 1f>
あん!*2=3c
[]

Here we're going to want to render Naruhodo's "waaaaaah" as a single word, so we don't want the brackets to automatically insert spaces, or else we'll end up with something like "waa aa aa aah". So I chose to remove all the brackets from Naruhodo's box in my translation:

$TRANSLATED
/5なるほどさん。=10あなた‥‥
[/3Mr. Naruhodo.=30You...
<wait_noanim 2d><b><26 1><person 25 148 0><bgtile 3><bg e><bgcolor 301 8 1f>
<sound 48 1>*1<sound 48 1>
/2この私に、=0cウソをついたのねっ!
/2you lied to me, didn't you?]
<nextpage_button><person 0 0 0><hideperson><26 0><person a 3e8 3e8><bg 3>
<name 300>
/6‥‥‥‥/8‥‥/a‥‥/c‥‥=46<b>
/6.../8.../a.../c...=46<b>
<sound 4c 1>*2<bgcolor 301 8 1f><person a 1cb0 1cb0><bgcolor 301 8 1f>=05<sound 4c 1>
*2=05<bgcolor 301 8 1f>
/2ごめん
/2So-sor
<bgcolor 301 8 1f>
なさ
r
<bgcolor 301 8 1f>
わわ
yyywaaaa
<sound 4c 1>*2<bgcolor 301 8 1f>
ああああ
aaaa
<bgcolor 301 8 1f>
ああ
aaaa
<bgcolor 301 8 1f>
あん!*2=3c
aaah!*2=3c
$END_TRANSLATED

Whenever you do something like this, make sure to test your translation in-game to make sure it renders the way you think.


4 Translation


4.1 General guidelines

Note that I don't feel that strongly about any of the following guidelines, it's just that we ought to just pick some policies and stick with them to be consistent across the entire translation. Feel free to add to this section if you feel the need to make new policies.


4.2 Names & phrases tables

Here is a list of common names and phrases in the game. All translators should be translating these the same way to be consistent, thus this table.

NameEnglish translationComments
美柳ちなみDolores WillowMy invention
呑田菊三Jack RichfordMy invention
なるほどPhoenix
成歩堂龍一Phoenix Wright
裁判長Judge/Your Honor
綾里千尋Mia Fey
綾里真宵Maya Fey
綾里春美?
狩魔冥?
星影宇宙ノ介Marvin Grossberg
亜内検事Winston Payne
ゴドー検事GodotFrom Samuel Beckett's play, "Waiting for Godot"
怪人☆仮面マスクThe Mysterious Mask

PhraseEnglish translationComments
勇盟大学Phamous UniversityAttempt at translating the pun

This list is still very incomplete; it will be filled in gradually. This is not so crucial anyway because a search-and-replace can always be performed to make things consistent.