How to create a new translation - zladx/LADX-Disassembly GitHub Wiki

Although Link’s Awakening was released in four different languages (Japanese, English, French, German), numerous fan translations popped up over the years.

Usually these translations resorted on binary hacking, Having a disassembly makes translating the game much easier.

This is a work in progress. Until this guide is completed, you can also browse Kelly's translation guide and notes.

First, for your new target language, choose a two-letters code (ex. Esperanto -> EO)

In the Makefile, duplicate the section for your source language. If you're editing the English version, duplicate the French or German version instead.

In this new section, replace every mention of your source language with your new language.

You'll typically want to replace:

• The target name (ex. azlf.gbc -> azleo.gbc)
• The language code (ex. -DLANG=FR -> -DLANG=EO)
• The path to the directory containing localized resources (ex. revisions/G0/ -> revisions/E0)

Notes:

• These compile flags set header values which aren't displayed in the game: --non-japanese, --title "ZELDA", --game-id "AZLX". They might get displayed by some emulators. You can change them, or leave them alone.
• If you want, you can change the version. It gets passed to src/options.asm.
• Once you've verified that everything works, you can delete the azlx-r1_LDFLAGS line. it just fills unused space with garbage data from another language's ROM, to match the checksum of the original release. Same for the filename at the end of the src/main.azlx-r1.o: line.

src/options.asm contains (among others) build options relevant to each language.

Copy-paste one of these blocks, and replace the original two-letters language code with your own (ex. ELIF ("{LANG}" == "FR") -> ELIF ("{LANG}" == "EO")).

The main folders just contain the English text and graphics. For French, German and Japanese, go into the revisions/ folder, and duplicate a directory (ex. revisions/F0 -> revisions/E0).

If you're translating from English, you can then copy the English dialog files from src/text/*.asm to revisions/E0/src/text/: this will make a good base to work on.

Notes:

• Even if you start from the English translation, basing your revisions/XX folder on an existing one will give you a good idea of the different elements to localize.

Now make azleo.gbc should compile without errors. Let's get translating!

The source-code uses several ways to localize content:

• Language-specific resources. These are files in the revisions/XX/ folders. A file present in the proper revisions/ folder automatically override the same file in the main source code. This is the main way to translate text or graphics.
• Compile-time options. These are the options declared in src/options.asm. They tune a localized version in a specific way.
• Ifdefs statements. These are IF "{LANG}" == "XX" statements in the assembly code files. They allow for a lot of fine tuning, but can get messy if used too much.

A localization will mostly make use of language-specific resources; but you may find the need to use the other available mechanisms.

Simply edit the files in revisions/src/text/dialog_**.asm with your favorite text editor.

If you start from English, to make the localization process easier, the script mentions the speaker name before each dialog line.

Notes:

• There are (almost) no restrictions on the script size. However, if your target language has way more words than English, the dialog files might excess the bank max size (4 Ki each). In that case, you'll probably want to add an extra dialog file.

  Try to use dialog5.asm first (it is only used in the Japanese version, and is empty in all other locales, but the space is available). Otherwise, add another file in an unused bank at the end of the ROM.

TODO

The menus (file selection, name picker, save screen, game over, etc.) do not use strings stored as text. Instead they use tilemaps directly referencing the font tiles.

This means you'll need to:

• translate the menu tiles (in src/gfx/menus/*.png),
• then edit the tilemap for the different menus (in src/data/backgrounds/menu_*.tilemap.encoded).

See src/data/backgrounds/README.txt for how to decode the tilemaps, edit them, and re-encode them.

Notes:

• You can also do binary hacking instead, and edit the raw encoded commands of the tilemaps. Depending on your programming background, this may be easier than setting up a tilemap editor.

Many small localized graphics are scattered in the game:

• Shop signs,
• Map legend,
• Printing UI,
• etc.

These are mostly in revisions/XX/src/gfx/, and shouldn't be hard to localize: just edit the relevant PNG file.

TODO: explain how to use the built-in language debugger.

If you use a character like ë which is not available in whatever language version of the game you are editing without editing the charmap (Character Map) file, you will see an unmapped character error when making the file and when playing the file that missing character will appear as a random garbled tile.

The main font is stored as a graphic in src/gfx/fonts/font.cgb.png. You can add new characters in the space available. They are stored in hexadecimal order, meaning after A1 would be A2, etc, which is how you know the tile number for any new characters drawn into a blank space. Then open the dialogs charmap (src/constants/charmaps/dialogs.asm). You will see lines of code like this

charmap "a", $61

This means when you type the letter a into dialog, the tile $61 from the dialog text alphabet graphic will be printed (appear) on the game screen.

You can map multiple different letters to the same tile, which is useful to accommodate for keyboard differences between translators, for example:

charmap "'", $5E charmap "’", $5E

Now typing either the American or European apostrophe will both produce the same apostrophe tile in the game, instead of one producing the apostrophe and the other producing a garbled tile.

You can also map multiple characters to a tile, for example oe could map to the ö tile, as we see in examples like charmap "<flower>", $d9

TODO: expand on this.

The name your character screen draws its info from separate files compared to the dialog.

You'll need to to edit src/constants/charmaps/name_entry.asm.

You'll also need to add your new characters to the tilemap of the name picker menu.

TODO: explain how to do this.

Diacritics, also known as accent marks, dakuten, and umlauts, can be added to the tops of letters without requiring them to have their own special letter drawn in the alphabet graphics. This can save a lot of letter space on your alphabet map. For example, tiles for e, a, o, u, i, ¨ would only take 6 alphabet tiles, instead of tiles for e, ë, a, ä, o, ö, u, ü, i, ï taking up 10 alphabet tiles.

The default Japanese and German games use these features. Diacritics can also be used to display a letter or symbol (emoji, et cetera) which would normally be too tall to fit in a single tile.

Compile with __DIACRITICS_SUPPORT__ = TRUE to enable support for diacritics.

As the original Japanese has two different diacritics ( ゛and ° ), the code originally has support for two different options you can make look like whatever you want. To use them, you should:

1. Tweak the diacritic graphics to suit your needs.

   The diacritic tiles are stored three times, in three different tilesets:

   • inventory_overworld_items.dmg/cgb,
   • inventory_indoor_items.cgb,
   • ending_1.cgb (in the middle of the water splash tiles)

2. Edit the charmap, to select which diacritic should be displayed over which letter.

   For this refer to the localized CodepointToDiacritic in codepoints_to_diacritic.asm.

Adding extra diacritics (to have more than the two available slots) is doable, but requires a bit more tweaking.

If you need more than two diacritics, you'll need to:

• Edit the assembly code that uses CodepointToDiacritic, so that it can handle values other than 0, 1 and 2;
• Add the new diacritic tile in a tileset, picking one that is always loaded when a dialog is present (not a lot of space is available there),
• Add the new diacritic to the credits tileset (to use it in the Windfish dialog, if you ever need it).

The "Link's Awakening: Turbo Français" mod adds a new diacritic by dynamically swapping a tile used in the inventory. You can have a look at the diacritics-swapping commits – or find another solution; other ways are probably possible.

Here are some localization projects based on the disassembly. You can look at them for inspiration or reference.

• Link's Awakening Norvegian translation (by @Tobiasvl): https://github.com/tobiasvl/zelda-links-awakening-NO
• Link's Awakening: Turbo Français mod (by @kemenaran): https://github.com/kemenaran/LADX-Disassembly/tree/turbo-francais-1.2
• Link's Awakening Toki Pona translation (by @wasokeli): https://github.com/wasokeli/LADX-Disassembly/tree/toki-pona