diff --git a/docs/en_US/translations.rst b/docs/en_US/translations.rst
index 0cf0f2ca..d5191f40 100644
--- a/docs/en_US/translations.rst
+++ b/docs/en_US/translations.rst
@@ -2,37 +2,38 @@
Translations
************
-pgAdmin supports multiple languages using the `Flask-Babel
-`_ Python module. A list of supported
-languages is included in the **web/config.py** configuration file and must be
-updated whenever langauges are added or removed.
+pgAdmin supports multiple languages using the `Flask-Babel
+`_ Python module. A list of supported
+languages is included in the **web/config.py** configuration file and must be
+updated whenever languages are added or removed with
+`ISO 639-1 `_ (two letter) language
+codes. The codes are named **$LANG** in this document.
Translation Marking
===================
Strings can be marked for translation in either Python code (using **gettext()**)
-or Jinja templates (using **_()**). Here are some examples that show how this
+or Jinja templates (using **_()**). Here are some examples that show how this
is achieved.
Python::
errormsg = gettext('No server group name was specified')
-
+
Jinja:
.. code-block:: html
-
+
.. code-block:: html
{{ _('%(appname)s Password Change', appname=config.APP_NAME) }}
-
+
.. code-block:: javascript
define(['sources/gettext', ...], function(gettext, ...){
...
-
var alert = alertify.prompt(
gettext('Password Change'),
gettext('New password for %(userName)s', {userName: 'jsmith' }),
@@ -40,83 +41,34 @@ Jinja:
)
})
-
+
Updating and Merging
====================
-Whenever new strings are added to the application, the template catalogues
-(**web/pgadmin/messages.pot**) must be updated and the existing catalogues
-merged with the updated template and compiled. This can be achieved using the
-following command from the **web** directory, in the Python virtual environment
-used for pgAdmin:
+Whenever new strings are added to the application, the template catalogue
+(**web/pgadmin/messages.pot**) and the existing translation
+catalogues (**web/pgadmin/translations/$LANG/LC_MESSAGES/messages.po**) must be updated
+and compiled. This can be achieved using the following commands from the
+**web** directory in the Python virtual environment for pgAdmin:
.. code-block:: bash
- (pgadmin4)piranha:web dpage$ pybabel extract -F babel.cfg -o pgadmin/messages.pot pgadmin
-
-For example:
-
-.. code-block:: bash
+ (pgadmin4) user$ pybabel extract -F babel.cfg -o pgadmin/messages.pot pgadmin
- (pgadmin4)piranha:web dpage$ pybabel extract -F babel.cfg -o pgadmin/messages.pot pgadmin
- extracting messages from pgadmin/__init__.py
- extracting messages from pgadmin/about/__init__.py
- extracting messages from pgadmin/about/hooks.py
- extracting messages from pgadmin/about/views.py
- extracting messages from pgadmin/about/templates/about/index.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/browser/__init__.py
- extracting messages from pgadmin/browser/hooks.py
- extracting messages from pgadmin/browser/views.py
- extracting messages from pgadmin/browser/nodes/CollectionNode.py
- extracting messages from pgadmin/browser/nodes/ObjectNode.py
- extracting messages from pgadmin/browser/nodes/__init__.py
- extracting messages from pgadmin/browser/nodes/server_groups/__init__.py
- extracting messages from pgadmin/browser/nodes/server_groups/hooks.py
- extracting messages from pgadmin/browser/nodes/server_groups/views.py
- extracting messages from pgadmin/browser/templates/browser/body.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/browser/templates/browser/index.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/browser/templates/browser/messages.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/help/__init__.py
- extracting messages from pgadmin/help/hooks.py
- extracting messages from pgadmin/help/views.py
- extracting messages from pgadmin/redirects/__init__.py
- extracting messages from pgadmin/redirects/views.py
- extracting messages from pgadmin/settings/__init__.py
- extracting messages from pgadmin/settings/hooks.py
- extracting messages from pgadmin/settings/settings_model.py
- extracting messages from pgadmin/settings/views.py
- extracting messages from pgadmin/templates/base.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/templates/security/change_password.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/templates/security/fields.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/templates/security/forgot_password.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/templates/security/login_user.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/templates/security/messages.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/templates/security/panel.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/templates/security/reset_password.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/templates/security/watermark.html (extensions="jinja2.ext.autoescape,jinja2.ext.with_")
- extracting messages from pgadmin/test/__init__.py
- extracting messages from pgadmin/test/hooks.py
- extracting messages from pgadmin/test/views.py
- extracting messages from pgadmin/utils/__init__.py
- extracting messages from pgadmin/utils/views.py
- writing PO template file to pgadmin/messages.pot
-
-Once the template has been updated, it needs to be merged into the existing
-message catalogues, for example:
+Once the template has been updated it needs to be merged into the existing
+message catalogues:
.. code-block:: bash
- (pgadmin4)piranha:web dpage$ pybabel update -i pgadmin/messages.pot -d pgadmin/translations
- updating catalog 'pgadmin/translations/fr/LC_MESSAGES/messages.po' based on 'pgadmin/messages.pot'
+ (pgadmin4) user$ pybabel update -i pgadmin/messages.pot -d pgadmin/translations
Finally, the message catalogues can be compiled for use:
.. code-block:: bash
- (pgadmin4)piranha:web dpage$ pybabel compile -d pgadmin/translations
- compiling catalog 'pgadmin/translations/fr/LC_MESSAGES/messages.po' to 'pgadmin/translations/fr/LC_MESSAGES/messages.mo'
+ (pgadmin4) user$ pybabel compile -d pgadmin/translations
-Adding a new Language
+Adding a New Language
=====================
Adding a new language is simple. First, add the language name and identifier to
@@ -125,15 +77,14 @@ Adding a new language is simple. First, add the language name and identifier to
# Languages we support in the UI
LANGUAGES = {
'en': 'English',
- 'fr': 'Français'
+ 'zh': 'Chinese (Simplified)',
+ 'de': 'German',
+ 'pl': 'Polish'
}
-Then, create the new message catalogue from the **web** directory in the source
-tree, in the Python virtual environment used for pgAdmin:
+Then, create the new message catalogue from the **web** directory in the source
+tree in the Python virtual environment for pgAdmin:
.. code-block:: bash
- (pgadmin4)piranha:web dpage$ pybabel init -i pgadmin/messages.pot -d pgadmin/translations -l fr
-
-This will initialise a new catalogue for a French translation.
-
+ (pgadmin4) user$ pybabel init -i pgadmin/messages.pot -d pgadmin/translations -l $LANG