From 63c05b1f29830caf11182c7bc2c5941f6139660b Mon Sep 17 00:00:00 2001 From: Stefan Kügel Date: Thu, 8 Dec 2022 17:41:39 +0100 Subject: Update of the README file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Stefan Kügel --- README | 258 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 241 insertions(+), 17 deletions(-) (limited to 'README') diff --git a/README b/README index 56594ba7..9af912b7 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/.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 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 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 -- cgit v1.2.3