diff --git a/docs/dev/translation.rst b/docs/dev/translation.rst
index 0fc02a7de..c070c36ea 100644
--- a/docs/dev/translation.rst
+++ b/docs/dev/translation.rst
@@ -6,23 +6,29 @@ run these commands in the root directory of searx
 Add new language
 ~~~~~~~~~~~~~~~~
 
-``pybabel init -i messages.pot -d searx/translations -l it``
+.. code:: shell
+
+    pybabel init -i messages.pot -d searx/translations -l it
 
 Update .po files
 ~~~~~~~~~~~~~~~~
 
-``./utils/update-translations.sh``
+.. code:: shell
+
+    ./utils/update-translations.sh
 
 You may have errors here. In that case, edit the
 ``update-translations.sh`` script to change ``pybabel`` to
-``pybabel-python2``
+``pybabel-python2 or pybabel2``
 
 After this step, you can modify the .po files.
 
 Compile translations
 ~~~~~~~~~~~~~~~~~~~~
 
-``pybabel compile -d searx/translations``
+.. code:: shell
+
+    pybabel compile -d searx/translations
 
 Transifex stuff
 ~~~~~~~~~~~~~~~
@@ -32,12 +38,14 @@ Init Project
 
 .. code:: shell
 
+    tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/
+
     tx set --auto-local -r searx.messagespo 'searx/translations/<lang>/LC_MESSAGES/messages.po' \
     --source-lang en --type PO --source-file messages.pot --execute
 
-http://docs.transifex.com/developer/client/set
+http://docs.transifex.com/client/init/
 
-*TODO: mapping between transifex and searx*
+http://docs.transifex.com/client/set/
 
 Get translations
 ^^^^^^^^^^^^^^^^
@@ -46,29 +54,27 @@ Get translations
 
     tx pull -a
 
-http://docs.transifex.com/developer/client/pull
+http://docs.transifex.com/client/pull
 
 Upload source File
 ^^^^^^^^^^^^^^^^^^
 
-::
+.. code:: shell
 
     tx push -s
 
 Upload all Translation
 ^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code:: shell
 
     tx push -s -t
 
-upload specifc Translation (only for admins)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+upload specifc Translation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-::
+.. code:: shell
 
     tx push -t -l tr
 
-http://docs.transifex.com/developer/client/push
-
-*TODO: upload empty files? (new translations)*
+http://docs.transifex.com/client/push