path: root/README

This repository contains the GNU Taler web site www.taler.net.

The web site consists of basically static HTML. However, the static HTML is
run through the Jinja2 template processor for internationalization.

Structure:

/template/
  Basically, you edit the English *.html.j2 files in /template/, and then run
  the Python script to generate static HTML. To facilitate translation, all
  English text in the HTML is marked for GNU Gettext using Jinja2 mark-up.

/common/
  This directory contains files shared between the various HTML pages, such
  as our navigation bar.

/locale/
  The translations of the strings into the various languages are in the
  /locale/ directory.

/build-system/
  This directory contains JavaScript from other projects which we redistribute,
  such as bootstrap and jquery.

/static/
  This directory contains static resources that are language-independent
  and never change.

/inc/
  This directory contains various Python scripts that are included during
  the pre-processing with Jinja2.
  
/rendered/
  This directory contains the build of the web site after you commanded 'make'.
  Open this file with your favourite browser and check the final result with other browsers.


How To  -  Instructions for how to generate the HTML page(s):

A. Preparing the environment:

If not already installed, please install according to your needs and your OS:

# apt install python3-jinja2 python3-babel python3-distutils
# apt install python3-ruamel.yaml
# apt install python3-lxml python3-bs4
# apt install git

-> On some distros, you may need to use `pip install ruamel.yaml`

For read-only access pass 
# git clone https://git.taler.net/www.git 

If you think you are trustworthy enough to deserve edit rights as a contributor 
with Git access, you can apply for such by signing and mailing the 
Copyright Assignment Agreement (https://taler.net/pdf/copyright.pdf) 
to ensure that the GNUnet e.V. --- Taler Systems SA agreement on licensing and 
the collaborative development of the GNUnet and GNU Taler projects 
(https://git.gnunet.org/gnunet-ev.git/tree/gnunet_taler_agreement.tex) is satisfied.

The agreements ensure that the code will continue to be made available under free 
software licenses, which gives developers the freedom to move code between GNUnet 
and GNU Taler without worrying about licenses and the company the ability to 
dual-license (for example, so that we can distribute via app-stores that are hostile 
to free software).

Minor contributions do not require copyright assignment (basically, anyone without Git access). 
Pseudonymous contributions are accepted, in this case simply sign the agreement 
with your pseudonym. Scanned copies are sufficient, but snail mail is preferred.

====================
Debian prerequisites
====================

Simply install:

# apt install python3-ruamel.yaml python3-jinja2 python3-babel git python3-lxml python3-bs4

====================
NetBSD prerequisites
====================
Install python3.7, py37-babel, npm, nodejs from pkgsrc.

Adjust the values in config.mk:    PYTHON=python3.7    BABEL=pybabel-3.7

====================
Python virtual env
====================
* Install python3 i.e on Debian
```
# apt install python3
```
* Create virtual environment **.venv directory is excluded with git ignore paterns**
```
python3 -m venv .venv
```
* Activate the virtual environment
```
source .venv/bin/activate
```
* Install all requirements from [requirements.txt](requirements.txt) using pip
```
pip install -r requirements.txt


B. When reusing the existing web site from Git, get its files and folder structure:
# git clone git+ssh://git@git.taler.net/www.git

Change into the new folder and run:
./bootstrap
./configure
make

The website will be installed in the /rendered/ directory.

If ./configure without parameters does not work, try ./configure --variant=/rendered/

Open the web site that results in /rendered/ or run
$ firefox rendered/en/index.html


C. Preparing for deployment:
When using a web site template from a dislocated web server, you will have to check whether all files are at your hand.
wget might eventually not retrieve all the files necessary for building the local site.

1. wget -r https://server.foo/taler/index.html
2. Download the website with all files to your home folder
3. Check media resources of the web site by right-clicking and selecting from the browser sub menu 'Show page info'
4. Compare and get the missing files of the online web site which will serve as your main source
5. Add image resources to /images/
6. Add fonts to /static/fonts/
7. Add or modify CSS files in /static/css/
8. Add JS files in /static/js/
9. Add or modify *.html.j2 files in /template/
10. Commit all files to Git

Then run in the new web site's home folder (e.g. ~/www/):
./bootstrap
./configure
make

If the page finally builds well, proceed with the following steps:

1. Insert internationalization mark-up tags around any text string for translation:
{% trans %} foo text {% endtrans %}
2. Modify shared HTML logic in /common/
3. Adjust navigation.j2.inc, header.j2.inc and footer.j2.inc in /common/
4. Add more *html.j2 files to expand the web site structure and paste their URLs into navigation.j2.inc
5. Modify HTML code in the other *.html.j2 files according to your needs and wishes
6. Test out and deactivate unnecessary Javascript
7. Check for typos and mistakes in the text strings
8. Check the translation strings in /locale/*/LC_MESSAGES/messages.po
9. Clean up unnecessary files and folders
10. Push all files to Git
11. Review the results before deploying the new web site, then publish it on the internet


D. Internationalization:
Weblate is used as Web-based platform for internationalization. Before registering new projects on Weblate, 
please read the development docs at https://docs.taler.net/developers-manual.html#internationalization 
for information on how to create projects, components, translations, and general settings.

The original source text for translation stems from the *.html.j2 files in /template/ and from *.j2 files in /common/ 
wherever text is in between the mark-up tags {% trans %} and {% endtrans %}. 
The command 'make' gathers all these strings from all HTML files and merges them into the file messages.pot in /locale/.
The base language is English in our case.

Weblate has to be set up as follows:

1. Fill in the variables for the Weblate project in 'Settings' on https://weblate.taler.net/settings/gnu-taler/#basic

At 'Basic'
- Project name [the name of the project on the Weblate platform; here: GNU Taler]
- Project website [here: https://taler.net/]
- Mailing list [email address of the responsible for the translators' mailing list]
- Translation instructions [here: Mailing list for translators: languages@taler.net]

At 'Access'
- Public

At 'Workflow' activate:
- Set "Language-Team" header
- Use shared translation memory
- Contribute to shared translation memory
- Enable hooks: activated
- Language aliases [left empty]
Leave deactivated:
- Enable reviews 
- Enable source reviews

Go to https://weblate.taler.net/manage/ssh/
scroll down to 'Add host key' and let Weblate integrate the SSH host key 
by entering into the form the domain name for the project's website (here: taler.net, 'Port' left empty).

2. Add components on https://weblate.taler.net/settings/gnu-taler/#components 
    'Components' is a synonym for the languages Weblate shall offer for collaborative translation, 
    e.g. for the component 'Main web site' at https://weblate.taler.net/settings/gnu-taler/main-web-site/:
    
At 'Basic'
- Component name [e.g. 'Main web site']
- Translation license - GNU General Public License v3.0 or Later
- Contributor agreement [left empty]
- Source string bug reporting address [email address of the Weblate admin/"Superuser"]
- Priority: Medium
- Leave deactivated: 
  - Restricted component
  - Share in projects
  
At 'Translation'
- Turn on suggestions
- Allow translation propagation

At 'Version control'
- Version control system: Git
- Source code repository: git+ssh://git@git.taler.net/www.git
    ==> note that the repository indication should always end with '.git' otherwise you might experience difficulties. 
    git remote -v displays the path to <reponame> without .git, so please add.
- Repository branch: master
- Repository push URL: git+ssh://git@git.taler.net/www.git
    ==> note that the repository indication should always end with '.git' otherwise you might experience difficulties. 
    git remote -v displays the path to <reponame> without .git, so please add.
- Repository browser [left empty]
- Push on commit: deactivated
- Age of changes to commit: 24
- Merge style: Rebase
- Lock on error: activated

At 'Commit messages'
- Commit message when translating:
Translated using Weblate ({{ language_name }})
Currently translated at {{ stats.translated_percent }}% ({{ stats.translated }} of {{ stats.all }} strings)
Translation: {{ project_name }}/{{ component_name }}
Translate-URL: {{ url }}

At 'Files'
- File format: gettext PO file
- Language filter: locale/*/LC_MESSAGES/messages.po
- Language filter: ^[^.]+$
- Source language: English
- Monolingual translations / Monolingual base language file [left empty]
- Edit base file: deactivated
- Intermediate language file [left empty]
- Template for new translations: locale/messages.pot
- Adding new translation: Create new language file
- Language code style: Default based on the file format

3. For all components 'Edit base file' in the settings (in the tab 'Files') has to be turned off, 
    because it is never a good idea to allow (anonymous) users to edit the base language file...
4. In 'Settings', 'Repository push URL' should never be left empty.
5. The messages.pot file in the local working tree /locale/ has to be pushed to Git. 
    Then, click in Weblate the 'Manage' link, search for the tab 'Repository maintenance', 
    then click on 'Update' or 'Pull'. Weblate pulls the base language strings.
6. Create new components in Weblate (languages to translate to). 
    Edit the strings in those components, preferably using the 'Zen' mode on Weblate (look for the pencil symbol to click!). 
    Don't forget to save after every edit. Finish with clicking 'Commit'. 
    Weblate automatically pushes to Git at a set time, e.g. every 24 hours. Manual pushes are allowed, too.
7. For building the web pages on a local machine, pull the messages.po files for all languages via Git (# git pull) and type 'make'. 
    Review the rendered pages.
8. Changes in the base language (English) have to be done in the *.html.j2 files in /template/. 
    After every update of these files, the messages.pot AND the respective messages.po files 
    for any other language MUST be pushed to Git.
9. Changes in any other language than the base language have to be edited with Weblate, 
    then committed/pushed from Weblate to Git, and 'git pull'ed to a local machine where 'make' builds the web pages for reviewing.
10. If the base language (English) did not need any changes, consequently 
    NO message.po file in /locale/*/LC_MESSAGES/ needs to be pushed to Git, 
    because Weblate serves already as the preferred tool for manipulating all the different message.po files.


NB: As an alternative to Weblate, language strings still may be manually edited in the .po-files 
    - using plain text editors or the poedit program if preferred. 
    This requires a manual update in Weblate, though.

If Weblate sends a message like "Missing commits in the Weblate repository" 
    it needs a manual update of files from the Git repository. 
    Weblate's own local repository obviously does not get your *.po files automatically. 
    To solve this, click in Weblate the 'Manage' link, search for the tab 'Repository maintenance' and then click on 'Update'.

Workaround for the 'lock' issue:
    Weblate locks translations automatically after two Weblate administrators pushed one after the other. 
    To solve this issue, the successor admin has to unlock translations on Weblate and 
    synchronize Weblate's repository and local repositories with the corresponding Git repository. 
    This means downloading the language files from Weblate's local repository to the admin's machine: 
    # git clone https://weblate.taler.net/git/gnu-taler/main-web-site/
    then copying the *.po files to the Git folder on the local machine, t.i. 
    #: ~/www
    pushing these files again to Git, 
    finally clicking on 'Update' in Weblate so that it syncs all language files in Weblate's own repository.

Translations components that are bound to a Git repository which is master branch (with ssh-based r/w access) have to denote 
    the repository push URL with git+ssh://git@git.taler.net/www.git
    which is the normal case while other components that share strings with other components like the Taler apps denote 
    'Source code repository' with weblate://project/component  (e.g. weblate://gnu-taler/wallet-android)
    and 'Repository push URL' left blank.
    For every linked component, the path to 'Monolingual base language file' has to point to the respective file, e.g.
    Wallet Android: wallet/src/main/res/values/strings.xml
    Point-of-Sale Android: merchant-terminal/src/main/res/values/strings.xml
    Cashier Android: cashier/src/main/res/values/strings.xml