******************************************************
*                                                    *
* Localization guidelines for Jessica's Cupcake Cafe *
*                                                    *
******************************************************

PREAMBLE:
---------
Jessica's CupcakeCafe was developed by a predominantly English-speaking development team. As such, all of the "original" art sources, text, user-interface (UI) layouts and fonts were created/chosen with the English language in mind. Every time this document refers to the "original" sources, it refers to the English source files.

If you are doing localization into any other language, please use the English assets as your reference source. Thank you!

This README file assumes that the reader (you) has prior knowledge in XML.

#############################
IF YOU KNOW WHAT YOU'RE DOING AND WANT A QUICK SUMMARY, GO TO THE CONCLUSIONS AT THE END OF THIS DOCUMENT...
#############################


PART 1: FOLDER STRUCTURE
------------------------

1) The main directory for all language-specific assets is /data/Languages
2) The Language folder has several subfolders - one for each language.
3) Each language subfolder's name follows the conventional two-letter ISO standard language codes (i.e. 'en' for English, 'de' for German, 'fr' for French, etc...). 
4) All language-localizable assets (such as signs, cutscenes, translated text, etc) are placed in these subfolders. When translating to another language (for example, German), make sure that all the files in /data/Languages/en (English) have their corresponding translated versions in /data/Languages/de (German). Failure to do so may prevent the game from starting.
5) For each language, the corresponding <language> nodes also need to be set in cupcakecafe.xml. 


PART 2: CONFIGURING CUPCAKECAFE.XML
-----------------------------------

1) The current language is set in /data/xml/cupcakecafe.xml
2) The default language is English (en) and is set in the /data/xml/cupcakecafe.xml configuration file between the <currentLanguage> tags. For example: <currentLanguage>en</currentLanguage>
3) The language code set by the <currentLanguage> tag MUST have an accompanying <language> tag with the following structure:

<language code="en">
    <directory>data/languages/en</directory>
    <localizedText>language_en.xml</localizedText>
</language>
 
4) If <currentLanguage> is set to '"de" (German), then you need to add an additional <language> tag:

<language code="de">
    <directory>data/languages/de</directory>
    <localizedText>language_de.xml</localizedText>
</language>

5) Take note of the two child tags within the language tags. The <directory> tag points toward the language subfolders pointed out in PART 1-3 above. The <localizedText> tag is the name of the language text file, which contains all of the game's text strings. The naming convention proposed is language_XX.xml, where "XX" is substituted for the two-letter language codes mentioned before in PART 1-3


PART 3: ART ASSETS
------------------

1) When replacing art assets, make sure that they have exactly the same dimensions as the original assets. Failure to do so will result in misaligned in-game art.
2) This is especially true with filmstrip animations. For example, if a filmstrip is made of 6 rows by 4 columns and each segment (i.e. frame) measures 32x32 pixels, the localized version MUST have the same specifications.
3) The localized file MUST be of the SAME type as the original (i.e. If the original is a PNG image, the localized version must also be a PNG). Failure to do so may prevent the game from loading properly.

PART 4: EDITING LANGUAGE_XX.XML
-------------------------------

1) The basic form of a text entry is as follows:

<String Name="WELCOME">Welcome</String>

2) You must ONLY edit the text BETWEEN the <String> tags. So if you were translating the above string in German, it would look like this:

<String Name="WELCOME">Wilkommen</String>
 
3) Do not touch anything else. If you do, bad things will happen.


PART 5: EDITING UI.XML
----------------------
1) The text formatting of a button, label, screen or pop-up may run a little off when translating from one language to another. In such instances, you will need to edit the /data/Languages/XX/ui.xml file.
2) The general form of the ui.xml file is as follows:

<Screens>
    <Screen Name="MAINMENU" PositionX="0" PositionY="0">		
	<Labels>
	    <Label Name="LOADING" PositionX="360" PositionY="300" Text="COMMON.LOADING" FontStyle="FONT.LABEL_LOADING_SCREEN"/>
	    <Label Name="LOADING_DOTS" PositionX="490" PositionY="300" FontStyle="FONT.LABEL_LOADING_SCREEN"/>
        </Labels>
    </Screen>
</Screens>

3) While most of the attributes are quite straightforward, take note that the attributes "Text" and "FontStyle" are linked to the language_xx.xml and resource.xml respectively. "Text" is the text string that appears on screen while FontStyle determines the font style, size as well as any effects or filters on the font.


PART 6: EDITING RESOURCE.XML 
----------------------------
1) If you are familiar with fonts, the many attributes in Resource.xml will seem familiar.
2) If a font is too big, or too small when used for a particular language, we advise that you CREATE A NEW <Font> tag and link to it from the relevant node in UI.xml.
3) We advise AGAINST altering existing fonts as some may be used in various different parts of the game - fixing the same font for one screen may screw up the formatting in another screen.



###############
#             #
#   SUMMARY   #
#             #
###############
How to make a new language pack (in this example, we'll do German):
1) Open /Data/xml/cupcakecafe.xml
2) Replace <currentLanguage>en</currentLanguage> with <currentLanguage>de</currentLanguage> ("de" is the ISO-standard two-letter language code for German).
3) Copy the <language code="en"> tags with its child nodes and paste it below, replacing all instances of "en" with "de". The finished node should look something like this:

<language code="de"><!-- German -->
   <directory>data/languages/de</directory>
   <localizedText>language_de.xml</localizedText>
</language> 

4) Go to /Data/Languages
5) If it doesn't already exist, create a new folder called "de"
6) Copy all the contents from /Data/Languages/en to /Data/Languages/de
7) Go to the new /Data/Language/de folder.
8) Rename language_en.xml to language_de.xml.
9) Get your artists to replace all the existing art assets with localized ones, using the same dimensions and file format.
10) Go into language_de.xml and translate all of the text strings between the <String></String> tags to German. For example, <String>Welcome</String> becomes <String>Wilkommen</String>
11) When you're done, you may delete the contents of the "en" folder to reduce the size of the localized build.
