--- a/rhodecode/i18n/how_to	Sun Jun 02 16:18:49 2013 +0200
+++ b/rhodecode/i18n/how_to	Sun Jun 02 21:47:48 2013 +0200
@@ -2,33 +2,66 @@
 # to create new language #
 ##########################
 
-Translations are also available on transifex under::
+Translations are available on transifex under::
 
     https://www.transifex.com/projects/p/RhodeCode/
 
-#this needs to be done on source codes, preferable on default/stable branches
- 
-python setup.py extract_messages <- get messages from project
-python setup.py init_catalog -l pl <- create a language directory for <pl> lang
-#edit the new po file with poedit or any other editor
-msgfmt -f -c <updated_file.po> <- check format and errors
-python setup.py compile_catalog -l pl <- create translation files
+Preferred method is to register on transifex and request new language translation.
 
-############# 
-# to update #
-#############
+manual creation of new language
++++++++++++++++++++++++++++++++
+ 
+Dowload sources of RhodeCode. Run::
 
-python setup.py extract_messages <- get messages from project
-python setup.py update_catalog -l pl<- to update the translations
-#edit the new updated po file with poedit
-msgfmt -f -c <updated_file.po> <- check format and errors
-python setup.py compile_catalog -l pl <- create translation files
+    python setup.py develop
+
+To prepare the enviroment
 
 
-###################
-# change language #
-###################
+Make sure all translation strings are extracted by running::
+
+    python setup.py extract_messages
+
+Create new language by executing following command::
+    python setup.py init_catalog -l <new_language_code>
+
+This creates a new language under directory rhodecode/i18n/<new_language_code>
+Be sure to update transifex mapping under .tx/config for new language
+
+Edit the new PO file located in LC_MESSAGES directory with poedit or your
+favorite PO files editor. Do translations and at the end verify the translation
+file for any errors. This can be done by executing::
+
+    msgfmt -f -c rhodecode/i18n/<new_language_code>/LC_MESSAGES/<updated_file.po>
+
+finally compile the translations::
+
+    python setup.py compile_catalog -l <new_language_code>
+
+##########################
+# to update translations #
+##########################
 
-`lang=pl`
+Fetch latest version of strings for translation by running::
+
+    python setup.py extract_messages
+
+Update PO file by doing::
+
+    python setup.py update_catalog -l pl<- to update the translations
+
+Edit the new updated po file. Repeat all steps after `init_catalog` step from
+new translation instructions
+
 
-in the .ini file
+########################
+# testing translations #
+########################
+
+Edit test.ini file and set lang attribute to::
+
+    lang=<new_language_code>
+
+Run RhodeCode tests by executing::
+
+    nosetests