summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorStefan Kügel <skuegel@web.de>2022-12-08 17:41:39 +0100
committerStefan Kügel <skuegel@web.de>2022-12-08 17:41:39 +0100
commit63c05b1f29830caf11182c7bc2c5941f6139660b (patch)
tree5ea69a158afaa1707abbcc8d1b267e904e4978b3 /README
parentc18ceb8ba0da10d71170617721d8b0ede568a87c (diff)
downloadwww-63c05b1f29830caf11182c7bc2c5941f6139660b.tar.gz
www-63c05b1f29830caf11182c7bc2c5941f6139660b.tar.bz2
www-63c05b1f29830caf11182c7bc2c5941f6139660b.zip
Update of the README file
Signed-off-by: Stefan Kügel <skuegel@web.de>
Diffstat (limited to 'README')
-rw-r--r--README258
1 files changed, 241 insertions, 17 deletions
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/<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