doc: Add translation documentation [VIPSUT-313]

README.md

@@ -8,116 +8,8 @@ The public web page acts as a client of the [VIPSLogic system](https://gitlab.ni
 
 Each organization within the VIPSLogic system will typically have their own VIPSWeb installation. Or the organization can choose to pull the data from VIPSLogic and display integrated in their own web sites.
 
+## Documentation
 
-## Requirements
-The system has been tested and found to run well on Ubuntu >= 18
-* The programming language is Python >= 3.6 
-* The web framework is currently [Django 3.1](https://docs.djangoproject.com/en/3.1/)
+* [Installation and configuration](./docs/install.md)
+* [Display details for new model](./docs/new_model_config.md)
+* [Translation](./docs/translation.md)
\ No newline at end of file
-* Apache web server with mod_wsgi compiled for Python 3
-
-## Install and setup
-1. Install and activate a virtual Python environment
-
-```
-python3 -m venv my_venv
-source my_env/bin/activate
-
-```
-
-2. Install all the requirements into the virtual environment. 
-Remember to be in the folder where the requirements.txt file is
-
-```
-pip install -r requirements.txt
-```
-
-3. Copy VIPSWeb/local_settings_sample.py into VIPSWeb/local_settings.py and adapt to your needs
-
-4. Run all database migrations
-
-```
-./manage.py migrate
-```
-
-## Running with mod_wsgi
-The official Django documentation for this [can be found here](https://docs.djangoproject.com/en/3.1/howto/deployment/wsgi/modwsgi/) 
-
-* If running on e.g. Ubuntu 18, please remember to install the `libapache2-mod-wsgi-py3` and not the `libapache2-mod-wsgi` package
-* Here's an example mod_wsgi configuration in an Apache2 virtualhost
-
-```
-        WSGIDaemonProcess vipsweb python-path=/opt/VIPSWeb/VIPSWeb python-home=/opt/VIPSWeb/py3dj3
-        WSGIProcessGroup vipsweb
-
-        WSGIScriptAlias / /opt/VIPSWeb/VIPSWeb/VIPSWeb/wsgi.py
-
-        <Directory /opt/VIPSWeb/VIPSWeb/VIPSWeb>
-                <Files wsgi.py>
-                        Require all granted
-                </Files>
-        </Directory>
-
-```
-
-## Instance configuration
-Each installation of VIPSWeb can be customized in several ways
-* The page title
-* Site owner/URL
-* Languages
-* Time zone
-* Point in time (for demoing out of season)
-* Which backend servers (instances of VIPSCoreManager and VIPSLogic) to use
-* Which organization(s) to show data from
-* Front page map configurations (center, zoom and height/width)
-* Which news message types to show on the front page
-* The menu items in the page header
-* The menus in columns below the map
-* Text in the footer
-* Settings for the date picker
-
-This is done by making a copy of `local_settings_sample.py` to `local_settings.py` and customizing it. `local_settings.py` is ignored by Git.
-
-
-
-## Showing a new model in the detail page (forecasts app)
-The VIPSWeb app has the tools to display results from model calculations. It fetches the data from the VIPSLogic backend. Each model has its own characteristics, and VIPSWeb needs to be told how to display the results from each model.
-
-![Detail view of results from an Apple scab model forecast](./docs/illustrations/detail_page.png "Detail view of results from an Apple scab model forecast")
-
-This has to be configured in the admin section of Django. Log in as administrator, or [create one](https://docs.djangoproject.com/en/3.1/intro/tutorial02/#creating-an-admin-user) if you haven't already.
-
-### Add result parameters for the model
-For each model, you have to specify the parameters (returned from the model calculations) that should be displayed in the table and in the diagram. All result parameters specified will be displayed in the table, but only the ones configured as "Model graph parameters" will be shown in the chart.
-
-Add a result parameter by clicking as shown below
-
-![Click Add to add a new result parameter](./docs/illustrations/add_result_param_1.png "Click Add to add a new result parameter")
-
-The result parameter form is shown below.
-* Namespace = The model ID (dictated by the model)
-* Key = The parameter ID (dictated by the model)
-* Name = The parameter name as displayed to users
-* Description = Further description of the parameter (currently not in use)
-* Measurementunit = How this parameter is measured. If not in any meaningful unit like &deg;C, use "Number"
-
-You can also add local names, by adding "Result parameter local". Use the ISO two-letter code for language and add your translation
-
-![The result parameter form](./docs/illustrations/add_result_param_2.png "The result parameter form")
-
-After saving, the parameter is listed among all the others in the VIPSWeb application, as shown below.
-
-![The list of result parameters](./docs/illustrations/add_result_param_3.png "The list of result parameters")
-
-
-### Configure a result parameter to be shown in the chart
-VIPSWeb uses [Highcharts](https://www.highcharts.com/) to generate charts, coupled with our own parameter-to-chart logic. **It's on our TODO list to replace Highcharts** To make the chart library recognize a chart parameter and tell it how it should be displayed, click "Add" in "Model graph parameters" as shown below.
-
-![Click Add to add a new model chart parameter](./docs/illustrations/add_result_param_4.png "Click Add to add a new model chart parameter")
-
-The form is show below
-* Model id (some parameters span models, e.g. WEATHER parameters, this is why you need to specify this)
-* Result parameter
-* Color hexcode = The color code for the chart item. [Read about it](https://www.w3schools.com/htmL/html_colors_hex.asp)
-* Highcharts type = [spline, area, bar, column, scatter]. [Read about it](https://www.highcharts.com/docs/chart-and-series-types/chart-types)
-
-![The model graph parameter form](./docs/illustrations/add_result_param_5.png "The model graph parameter form")
\ No newline at end of file

docs/install.md

+# Installation and configuration
+## Requirements
+The system has been tested and found to run well on Ubuntu >= 18
+* The programming language is Python >= 3.6 
+* The web framework is currently [Django 3.1](https://docs.djangoproject.com/en/3.1/)
+* Apache web server with mod_wsgi compiled for Python 3
+
+## Install and setup
+1. Install and activate a virtual Python environment
+
+```
+python3 -m venv my_venv
+source my_env/bin/activate
+
+```
+
+2. Install all the requirements into the virtual environment. 
+Remember to be in the folder where the requirements.txt file is
+
+```
+pip install -r requirements.txt
+```
+
+3. Copy VIPSWeb/local_settings_sample.py into VIPSWeb/local_settings.py and adapt to your needs
+
+4. Run all database migrations
+
+```
+./manage.py migrate
+```
+
+## Running with mod_wsgi
+The official Django documentation for this [can be found here](https://docs.djangoproject.com/en/3.1/howto/deployment/wsgi/modwsgi/) 
+
+* If running on e.g. Ubuntu 18, please remember to install the `libapache2-mod-wsgi-py3` and not the `libapache2-mod-wsgi` package
+* Here's an example mod_wsgi configuration in an Apache2 virtualhost
+
+```
+        WSGIDaemonProcess vipsweb python-path=/opt/VIPSWeb/VIPSWeb python-home=/opt/VIPSWeb/py3dj3
+        WSGIProcessGroup vipsweb
+
+        WSGIScriptAlias / /opt/VIPSWeb/VIPSWeb/VIPSWeb/wsgi.py
+
+        <Directory /opt/VIPSWeb/VIPSWeb/VIPSWeb>
+                <Files wsgi.py>
+                        Require all granted
+                </Files>
+        </Directory>
+
+```
+
+## Instance configuration
+Each installation of VIPSWeb can be customized in several ways
+* The page title
+* Site owner/URL
+* Languages
+* Time zone
+* Point in time (for demoing out of season)
+* Which backend servers (instances of VIPSCoreManager and VIPSLogic) to use
+* Which organization(s) to show data from
+* Front page map configurations (center, zoom and height/width)
+* Which news message types to show on the front page
+* The menu items in the page header
+* The menus in columns below the map
+* Text in the footer
+* Settings for the date picker
+
+This is done by making a copy of `local_settings_sample.py` to `local_settings.py` and customizing it. `local_settings.py` is ignored by Git.
+

docs/new_model_config.md

+# Showing a new model in the detail page (forecasts app)
+The VIPSWeb app has the tools to display results from model calculations. It fetches the data from the VIPSLogic backend. Each model has its own characteristics, and VIPSWeb needs to be told how to display the results from each model.
+
+![Detail view of results from an Apple scab model forecast](./illustrations/detail_page.png "Detail view of results from an Apple scab model forecast")
+
+This has to be configured in the admin section of Django. Log in as administrator, or [create one](https://docs.djangoproject.com/en/3.1/intro/tutorial02/#creating-an-admin-user) if you haven't already.
+
+## Add result parameters for the model
+For each model, you have to specify the parameters (returned from the model calculations) that should be displayed in the table and in the diagram. All result parameters specified will be displayed in the table, but only the ones configured as "Model graph parameters" will be shown in the chart.
+
+Add a result parameter by clicking as shown below
+
+![Click Add to add a new result parameter](./illustrations/add_result_param_1.png "Click Add to add a new result parameter")
+
+The result parameter form is shown below.
+* Namespace = The model ID (dictated by the model)
+* Key = The parameter ID (dictated by the model)
+* Name = The parameter name as displayed to users
+* Description = Further description of the parameter (currently not in use)
+* Measurementunit = How this parameter is measured. If not in any meaningful unit like °C, use "Number"
+
+You can also add local names, by adding "Result parameter local". Use the ISO two-letter code for language and add your translation
+
+![The result parameter form](./illustrations/add_result_param_2.png "The result parameter form")
+
+After saving, the parameter is listed among all the others in the VIPSWeb application, as shown below.
+
+![The list of result parameters](./illustrations/add_result_param_3.png "The list of result parameters")
+
+
+## Configure a result parameter to be shown in the chart
+VIPSWeb uses [Highcharts](https://www.highcharts.com/) to generate charts, coupled with our own parameter-to-chart logic. **It's on our TODO list to replace Highcharts** To make the chart library recognize a chart parameter and tell it how it should be displayed, click "Add" in "Model graph parameters" as shown below.
+
+![Click Add to add a new model chart parameter](./illustrations/add_result_param_4.png "Click Add to add a new model chart parameter")
+
+The form is show below
+* Model id (some parameters span models, e.g. WEATHER parameters, this is why you need to specify this)
+* Result parameter
+* Color hexcode = The color code for the chart item. [Read about it](https://www.w3schools.com/htmL/html_colors_hex.asp)
+* Highcharts type = [spline, area, bar, column, scatter]. [Read about it](https://www.highcharts.com/docs/chart-and-series-types/chart-types)
+
+![The model graph parameter form](./illustrations/add_result_param_5.png "The model graph parameter form")
\ No newline at end of file

docs/translation.md

+# Translate texts for the VIPS web site
+Version: 2022-09-22
+
+The VIPS web site is a web application tailored to display forecasts and messages from the VIPS system. Its content is translatable. This document describes how to do the translation.
+
+# Translation system – a brief introduction
+The VIPS web site is based on the web publishing platform called Django, which uses the widely known translation tool called Gettext. The translation happens inside the application code, where a phrase is defined to be translated, for instance:
+
+```
+{% trans "Welcome" %}
+```
+
+The application knows which language it should translate this phrase to. If it is Norwegian, it will 
+1. look up the phrase «Welcome» in the norwegian translation file
+2. find the translation for it in that file. This lookup looks like this:
+    ```
+    msgid "Welcome" 
+    msgstr "Velkommen"
+    ```
+3. return the translation «Velkommen»
+
+If there is no translation file for Norwegian, or the file exists, but the translation for that phrase is not found, the phrase is returned untranslated.
+
+## Several sub-applications – several translation files
+The web page application contains several sub applications. At the moment (2015! TODO Update) these applications are present:
+* VIPSWeb – the front page, menu system etc.
+* Forecasts – the pages with forecast lists and results
+* Messages – the pages with message lists and detailed messages
+* Information – a site for publication of a tree structure of documents/documentation
+
+For each application, there is one translation file for each language. So after unZIPing the files and folders, the folder structure thus like this:
+
+![Folder structure for translation in an app](./illustrations/translation_1.png "Folder structure for translation in an app")
+
+So for each application, you have a folder called «locale», which contains folders with each language abbreviated (nb = Norwegian, bg = Bulgarian). Each language specific folder contains a folder called LC_MESSAGES, and inside there you find at least one file ending with .po. And these files are where the translation is done. You can choose to do this with a text editor (like Notepad, jEdit, Emacs, Vim, etc.) - but NOT MS Word or any other word processor. OR you could do it the easy way, by using the free program called Poedit. You can download it from here: http://poedit.net/ . When you start the application, you're welcomed with this: 
+
+![Poedit](./illustrations/translation_2.png "Poedit")
+
+
+So you choose «Edit a translation», and select your translation file:
+
+![Select file in Poedit](./illustrations/translation_3.png "Select file in Poedit")
+
+After you've opened it, select each item/phrase an fill in the translation.
+
+![Translating phrases in Poedit](./illustrations/translation_4.png "Translating phrases in Poedit")
+
+After saving the file, the translation is completed. Return the translation by ZIP'ing the whole folder structure and return it by email to Bioforsk (or, if you're an advanced user, you can submit the updated translation files to the source code control system).
+
+## For the developer
+### Creating a new locale
+Entering each of the applications (/VIPSWeb, /forecasts, /messages), do:
+
+```bash
+django-admin.py makemessages -l [LANGUAGE]
+django-admin.py makemessages -d djangojs -l [LANGUAGE]
+```
+
+After that, you can edit the language files (see above)
+
+PLEASE NOTE: django-admin.py has been creating buggy information for plurals. Please check the header field of your newly created .po file. If the plural-forms header does not start with «nplurals=X;», then something has gone wrong. You can find the correct header here: http://localization-guide.readthedocs.org/en/latest/l10n/pluralforms.html 
+
+### Updating translation files 
+If you have added new translation keywords, do this in each of the applications:
+
+```bash
+django-admin.py makemessages -a [LANGUAGE]
+django-admin.py makemessages -d djangojs -a [LANGUAGE]
+```
+
+Then recompile the translation files (see below)
+
+### Compiling translation files
+Entering each of the applications (/VIPSWeb, /forecasts, /messages), do:
+
+```
+django-admin.py compilemessages
+```
\ No newline at end of file