[taler-www] branch master updated: Update of the README file

[gnunet]

This is an automated email from the git hooks/post-receive script.

skuegel pushed a commit to branch master
in repository www.

The following commit(s) were added to refs/heads/master by this push:
     new 63c05b1  Update of the README file
63c05b1 is described below

commit 63c05b1f29830caf11182c7bc2c5941f6139660b
Author: Stefan Kügel <skuegel@web.de>
AuthorDate: Thu Dec 8 17:41:39 2022 +0100

    Update of the README file
    
    Signed-off-by: Stefan Kügel <skuegel@web.de>
---
 README | 258 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 241 insertions(+), 17 deletions(-)

diff --git a/README b/README
index 56594ba..9af912b 100644
--- a/README
+++ b/README
@@ -1,36 +1,260 @@
-This repository contains the main GNU Taler Web site.
+This repository contains the GNU Taler web site www.taler.net.
 
-The Web site consists of basically static HTML. However, the static HTML is
+The web site consists of basically static HTML. However, the static HTML is
 run through the Jinja2 template processor for internationalization.
 
 Structure:
 
-INSTALL contains instructions for how to generate the HTML page(s).
-
-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
+/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/
+/common/
   This directory contains files shared between the various HTML pages, such
   as our navigation bar.
 
-locale/
+/locale/
   The translations of the strings into the various languages are in the
-  locale/ directory.
-
-static/
-  This directory contains static resources that are language-independent.
+  /locale/ directory.
 
-static/dist/
+/build-system/
   This directory contains JavaScript from other projects which we redistribute,
   such as bootstrap and jquery.
 
-template/news/ and template/financial-news/
-  This directory contains news items to be posted on the news page.
+/static/
+  This directory contains static resources that are language-independent
+  and never change.
 
-inc/
+/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 git
+
+-> On some distros, you may need to use `pip install ruamel.yaml`
+
+====================
+Debian prerequisites
+====================
+
+Simply install:
+
+# apt install python3-ruamel.yaml python3-jinja2 python3-babel git
+
+====================
+NetBSD prerequisites
+====================
+Install python3.7, py37-babel, npm, nodejs from pkgsrc.
+
+Adjust the values in config.mk:    PYTHON=python3.7    BABEL=pybabel-3.7
+
+       
+B. When reusing an existing web site from Git, get its files and folder 
structure:
+git clone git+ssh://git@git.taler.net/<repo-name>.git
+for example 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/
+
+Eventually you must install node-typescript, when your system is demanding for 
tsc.
+
+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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.