[taler-anastasis-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 anastasis-www.

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

commit fe1bb0a5e45c0c42d1a860660748a2885f77cc69
Author: Stefan Kügel <skuegel@web.de>
AuthorDate: Thu Dec 8 00:09:28 2022 +0100

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

diff --git a/README b/README
index cf99de6..415d32c 100644
--- a/README
+++ b/README
@@ -1,44 +1,249 @@
-This repository contains the main GNU Taler Web site.
+This repository contains the Anastasis SARL company web site.
 
-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.
-
+  /locale/ directory.
 
-dist/
+/build-system/
   This directory contains JavaScript from other projects which we redistribute,
   such as bootstrap and jquery.
 
-
-static/
+/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.
 
-news/ and financial-news/
-  This directory contains news items to be posted on the news page.
 
+How To  -  Instructions for how to generate the HTML page(s):
 
-inc/
-  This directory contains various Python scripts that are included during
-  the pre-processing with Jinja2.
+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.
 
-help/
-  ??
+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/anastasis-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 
--prefix=/tmp/ or ./configure --variant=/tmp/
+
+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/anastasis/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. ~/anastasis-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' 
+    (https://weblate.taler.net/settings/anastasis/):
+At 'Basic'
+- Project name [the name of the project on the Weblate platform; here: 
Anastasis]
+- Project website [here: https://anastasis.lu/]
+- Mailing list [email address of the responsible for the translators' mailing 
list]
+- Translation instructions [left empty]
+
+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: 
anastasis.lu, 'Port' left empty).
+
+2. Fill in the variables for all components. 
+    'Components' is a synonym for the languages Weblate shall offer for 
collaborative translation, 
+    e.g. for the component 'website' begin with 
https://weblate.taler.net/settings/anastasis/website/#basic):
+At 'Basic'
+- Component name [e.g. 'website']
+- 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
+
+At 'Version control'
+- Version control system: Git
+- Source code repository: git+ssh://git@git.taler.net/<reponame>.git 
+    (with <reponame> being the name of the Weblate project, e.g. anastasis-www)
+    ==> 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/<reponame>.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: activated
+- Age of changes to commit: 24
+- Merge style: Rebase
+- Lock on error: activated
+
+At 'Files'
+- File format: gettext PO file
+- Language filter: locale/*/LC_MESSAGES/messages.po
+- Language filter: ^[^.]+$
+- Source language: English
+- Monolingual translations: deactivated
+- 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 folder /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 http://weblate.taler.net/git/anastasis/website
+    then copying the *.po files to the Git folder on the local machine, t.i. 
+    #: ~/anastasis-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/<reponame>.git 
+    (<reponame> being the name of the Weblate project, e.g. anastasis-www)
+    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.