-------------------------------------------------------------------------------
---------        TRANSLATIONS - Ampache Translation Guide           -----------
-------------------------------------------------------------------------------

Contents:

 1. Introduction
 	a) Getting the Necessary tools
	b) Quick Reference
 2. Creating a New Translation
	a) Translating 
	b) Creating a MO file
 3. Updating an Existing Translation
 	a) Merging existing file
	b) Generating the MO file
 4. Questions? 

Introduction: 
	
  Ampache uses gettext to handle translating between different languages if 
  you are interested in translating Ampache into a new language or updating
  an existing translations simply follow the directions provided below.

  A) Getting the Necessary Tools

    Before attempting to translate Ampache into a new language we recommend
    contacting translations@ampache.org to make sure that nobody else is
    already working on a translation. Once you are ready to start your
    translation you will need to get a few tools

        - Gettext http://www.gnu.org/software/gettext/
                - xgettext (Generates PO files)
                - msgmerge (Merges old and new PO files)
                - msgfmt   (Generates the MO file from a PO file)

  B) Quick Reference

    Below are listed all of the commands you may have to run when working on 
    a translation

	# Gather All info
	./gather-messages.sh --all

	# Create New po file
	LANG=YOURLANG ./gather-messages.sh --init
	Example: LANG=ja_JP.UTF-8 ./gather-messages.sh --init
                 locale/ja_JP/LC_MESSAGES/messages.po will create.

	# Merge with existing po file
	./gather-messages.sh --merge

	# Combine Old & New po files
	msgmerge old.po messages.po --output-file=new.po

	# Generate MO file for use by gettext
	./gather-messages.sh --format

Creating a New Translation:

  A) Translating

    I do my best to keep an up to date po file in /locale/base feel free to 
    use this file rather than attempting to generate your own. If you would 
    like to gather a new PO file simply run /locale/base/gather-messages.sh 
    (Linux only)

    Once you have an up to date PO file you will need to figure out the 
    country code for the language you are translating into. There are many
    lists on the web.
    	http://www.gnu.org/software/gettext/manual/html_chapter/gettext_16.html

    Create the following directory structure and put your po file in the 
    LC_MESSAGES directory
    	/locale/<COUNTRY CODE>/LC_MESSAGES/

    Start Translating!

  C) Creating a MO File

    Once you have finished translating the PO file you need to convert it into
    a MO file in order for Gettext to be able to use it. Simply run the command
    listed below.
    
	msgfmt <DIR>messages.po -o <DIR>/messages.mo

    Unfortunately currently Ampache doesn't automatically detect new languages
    and thus you have to edit the code directly in order for it to pickup your
    new language. Find /lib/preferences.php and then find "case 'lang':" under
    the "create_preference_input" function and add a line for your own 
    language. For example to add en_US support add the following line

  echo "\t<option value=\"en_US\" $en_US_lang>" . _("English") . "</option>\n";

    Make sure that it comes after the <select> statement. This will be fixed
    for future releases... Sorry :S

Updating an Existing Translation:

  A) Merging existing file

    If you are updating an existing PO file you will need to merge the new
    file with the old so that you don't have to do everything over again. 
    simply run the following command. 

	msgmerge old.po messages.po --output-file=new.po

    Once you have created the new PO file translate it as you normally would.

  B) Generating the MO file

    Because this is an existing translation you do not have to modify ampache
    code at all simply run. 

	msgfmt <DIR>messages.po -o <DIR>messages.mo

    And then check it in the web interface!

Questions:

  If you have any questions or are unable to get gettext to work for you please
  feel free to contact us at translations@ampache.org or forums 
  http://ampache.org/forums/f7-Translations.html. Thanks!
  

Karl Vollmer
 http://www.ampache.org
 dev@ampache.org