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