Update 'release' to work with po4a

README.md

@@ -29,22 +29,23 @@ If you want to add a new image, use .png format if possible, and if it’s not a
 
 ## Translating
 
-### Please note: As of April 2021 we are only translating the following sections of the website:
+### For details on the website translation process, please consult the README file contained in the `translator-files/` folder
+
+#### Please note: if your language has no translated documents, please start with the following sections of the website:
 
 - Home page
 - Setup/Getting Started
-- Installation pages
+- Installation pages (Win, Linux, macOS)
 
 For translating text in the Jamulus application itself, please see [TRANSLATING.md](https://github.com/jamulussoftware/jamulus/blob/master/TRANSLATING.md)
 
-We collect changes to the English version of the site on a "changes" branch first. We then freeze changes prior to a Jamulus software release, and do a translation "sprint" over a couple of weeks when all translation takes place.
+We collect changes to the English version of the site on a "next-release" branch first. We then freeze changes prior to a Jamulus software release, and do a translation "sprint" over a couple of weeks when all translation takes place.
 
 ### Here’s the overall workflow
 
-1. Changes are first made to en-*.md files and committed to the “changes” branch.
+1. Changes are first made to EN *.md files and committed to the “next-release” branch.
 1. Once we’ve agreed the changes can go live (usually just before a software release), we then create GitHub issues for each language, tagged for that release. You can ask questions about the work there.
-1. We then create a “translation_[versionNo]” branch which contains all relevant changes in a single commit for easy translation (`git branch translation_[versionNo] release && git checkout translation_[versionNo] && git merge --squash changes`).
-1. Translators for each language then update any affected files in their language and open pull requests to merge them into the "translation_[versionNo]” branch. Those pull requests are linked to the relevant GitHub issue in step 2 so they can be tracked.
+1. Translators for each language then update any affected files by editing the .po files for their language in `translator-files/l10n/po/LANGUAGE/` and open pull requests to merge them into the "next-release” branch. Those pull requests are linked to the relevant GitHub issue in step 2 so they can be tracked.
 1. When all translations are merged (issues will then close automatically), we merge that new branch into the `release` branch, which is automatically made live on the production site.
 
 ### Points to note
@@ -53,7 +54,7 @@ We collect changes to the English version of the site on a "changes" branch firs
 
 - The homepage (https://jamulus.io/) is located in the repo root and named 1-[langCode]-index.html
 
-- Please do not add new or significantly modified content to a non-English .md or .html file. All changes must be made on the changes branch in English **first** after being [discussed here](https://github.com/jamulussoftware/jamulus/discussions).
+- Please do not add new or significantly modified content to a non-English .html file and do not edit **any** non-English .md files, as these changes would later be lost. All content changes must be made on the "next-release" branch in English **first** after being [discussed here](https://github.com/jamulussoftware/jamulus/discussions).
 
 - Please make sure you are aware of what stage of the workflow we are currently at by monitoring the [project board](https://github.com/orgs/jamulussoftware/projects/2), and on the Discord (or Matrix) discussion channel that you will be invited to join. This is where relevant deadlines and information will be posted during the translation sprint.
 
@@ -62,6 +63,8 @@ We collect changes to the English version of the site on a "changes" branch firs
 
 ## Adding a new language
 
+First open an issue so that the relevant folders and files can be created for your language in `translator-files/l10n/po/`.
+
 Make sure to add the language to the \_config.yml file (in the languages array).  At a minimum, the main includes for the wiki (see \_includes/wiki/) have to be translated.
 
 The navigation and general site-wide strings (see the \_data/ folder) and the homepage (see the 1-index.html file in the root of this repo) should also be translated.

po4a-create-all-targets.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# You need po4a > 0.54, see https://github.com/mquinson/po4a/releases
+# There is no need of system-wide installation of po4a
+# Usage: PERLLIB=/path/to/po4a/lib use_po.sh
+# you may set following variables
+# SRCDIR root of the documentation repository
+# PODIR place where to create the po
+# PUB_DIR place where to publish the localised files
+
+####################################
+# INITIALISE VARIABLES
+####################################
+
+SRCDIR_MODULE="./wiki/en"
+
+# place where the po files are
+if [ -z "$PO_DIR" ] ; then
+	PO_DIR="./translator-files/l10n/po"
+fi
+
+# place where the localised files will be
+if [ -z "$PUB_DIR" ] ; then
+	PUB_DIR="./wiki/"
+fi
+
+
+####################################
+# TEST IF IT CAN WORK
+####################################
+
+if [ ! -d "$SRCDIR_MODULE" ] ; then
+	echo "Please run this script from the documentation' root folder"
+	exit 1
+fi
+
+####################################
+# REMOVE .md FILE FOLDER
+####################################
+
+cd ./wiki/
+rm -rf de es fr it pt
+cd ../
+
+####################################
+# DEFINE ANTARA MODULES (md files)
+####################################
+
+use_po_module () {
+	lang=$1
+
+	while IFS= read -r -d '' file
+	do
+		basename=$(basename -s .md "$file")
+		dirname=$(dirname "$file")
+		path="${dirname#$SRCDIR_MODULE/}"
+
+		if [ "$dirname" = "$SRCDIR_MODULE" ]; then
+			potname=$basename
+			localized_file="$PUB_DIR/$lang/$basename.md"
+		else
+			potname=$path/$basename
+			localized_file="$PUB_DIR/$lang/$path/$basename.md"
+		fi
+
+
+		po4a-translate \
+			--format asciidoc \
+			--master "$file" \
+			--master-charset "UTF-8" \
+			--po "$PO_DIR/$lang/$potname.po" \
+			--localized "$localized_file" --localized-charset "UTF-8" \
+			--keep 80
+	done <   <(find -L "$SRCDIR_MODULE" -name "*.md"  -print0)
+
+}
+
+####################################
+# HANDLE ANTARA MODULES (md files)
+####################################
+
+while IFS= read -r -d '' dir
+do
+	lang=$(basename -s .md "$dir")
+	echo "$lang"
+	use_po_module "$lang"
+
+# Rename translated .md files with correct language prefixes
+#    cd $PUB_DIR
+#    if [ -d $lang ]; then
+#       cd "$lang"
+#        rename "s/^en-/$lang-/" *.md
+#        cd ../
+#    fi
+
+done <   <(find "$PO_DIR" -mindepth 1 -maxdepth 1 -type d -print0)
+

po4a-update-templates.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# You need po4a > 0.54, see https://github.com/mquinson/po4a/releases
+# There is no need of system-wide installation of po4a
+# Usage: PERLLIB=/path/to/po4a/lib make_pot.sh
+# you may set following variables
+# SRCDIR root of the documentation repository
+# POTDIR place where to create the .pot templates
+
+
+####################################
+# INITIALISE VARIABLES
+####################################
+
+# root of the documentation repository
+SRCDIR_MODULE="./wiki/en"
+
+# place where to create the .pot template files
+if [ -z "$POTDIR" ] ; then
+    POTDIR="./translator-files/l10n/templates"
+fi
+
+# place where the po files are
+if [ -z "$PO_DIR" ] ; then
+	PO_DIR="./translator-files/l10n/po"
+fi
+
+####################################
+# TEST IF IT CAN WORK
+####################################
+
+if [ ! -d "$SRCDIR_MODULE" ] ; then
+    echo "Error, please check that SRCDIR matches the root of the documentation repository"
+    echo "Your specified modules are in $SRCDIR_MODULE"
+    exit 1
+fi
+
+
+####################################
+# Process the documents
+####################################
+
+while IFS= read -r -d '' file
+do
+    basename=$(basename -s .md "$file")
+    dirname=$(dirname "$file")
+    path="${dirname#$SRCDIR_MODULE/}"
+
+    if [ "$dirname" = "$SRCDIR_MODULE" ]; then
+        potname=$basename.pot
+    else
+        potname=$path/$basename.pot
+        mkdir -p "$POTDIR/$path"
+    fi
+
+    po4a-gettextize \
+        --format asciidoc \
+        --master "$file" \
+        --master-charset "UTF-8" \
+        --po "$POTDIR/$potname"
+
+    for lang in $(ls "$PO_DIR" ); do
+
+        po_file="$PO_DIR/$lang/${potname%.pot}.po"
+
+        # po4a-updatepo would be angry otherwise
+        sed -i 's/Content-Type: text\/plain; charset=CHARSET/Content-Type: text\/plain; charset=UTF-8/g' "$po_file"
+
+        if ! po4a-updatepo \
+            --format asciidoc \
+            --master "$file" \
+            --master-charset "UTF-8" \
+            --po "$po_file" ; then
+        echo ""
+        echo "Error updating $lang PO file for: $adoc_file"
+
+        fi
+    done
+
+done <   <(find -L "$SRCDIR_MODULE" -name "*.md" -print0)
+
+echo ""
+echo "REMOVE TEMPORARY FILES"
+
+for lang in $(ls "$PO_DIR" ); do
+	rm "./translator-files/l10n/po/$lang/"*.po~
+done

translator-files/README.md

@@ -0,0 +1,31 @@
+# Translation:
+
+-   Navigate to `l10n/po/YOUR-LANGUAGE/`. Translate the content of the .po files in your editor of choice (QtLinguist, Lokalize, OmegaT...).
+    - A number of files in this folder do not need to be translated. These are:
+        - Administration.po
+        - Central-Servers.po
+        - Compiling.po
+        - Linux-Install-Script.po
+        - Multiple-Audio-Interfaces.po
+        - Onboarding.po
+        - Server-Rpi.po
+        - Software-Synth.po
+        - Sound-Devices.po
+        - index.po
+-   Set the lang: parameter to your language code at the beginning of the file (it, fr, de, etc.) and make sure the permalink: parameter (e.g. /wiki/Client-Troubleshooting) stays the same.
+-   Submit a Pull Request with the translated .po files. **DO NOT** edit any .md files in the /wiki/ folder.
+
+## Translate a new language
+
+If you wish to translate to a language for which there is no folder in `translator-files/l10n/po/`, please open an issue and request that it be created.
+
+### Suggested editors:
+
+- OmegaT (cross-platform): the most complete and advanced, but also somewhat more complex. A guide is included in this folder.
+- QtLinguist (cross-platform): if you've done app translations you should feel comfortable with this. However, you have to open files one by one and until you do, you can't know the state of the translation.
+- Lokalize (Linux): GUI similar to QtLinguist but more complete.
+    - This application can give you an overview of the translation progress of all files. Click on `Project > Create software translation project`. A window will open asking where to store the `index` file - choose anywhere you want. Now another window will open. In "Root folder" point it to the directory where all the .po files for your language are. Click on "Apply" and "OK". Now you will be shown an overview of the state of all the translations. Double-click on one to go to that file. If you are comfortable with this editor and use Linux, it's a very recommendable option if you don't want to get into the complexities of OmegaT.
+- Virtaal (cross-platform)
+- Gtranslator (Linux)
+
+For short edits or single file translations, QtLinguist, Lokalize or a similar editor might be simpler to use. For working through all the files, OmegaT will be much more suitable (see guide).

translator-files/l10n/po/de/Adminstration.po

@@ -0,0 +1,40 @@
+# SOME DESCRIPTIVE TITLE
+# Copyright (C) YEAR Free Software Foundation, Inc.
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"POT-Creation-Date: 2021-06-03 15:49+0200\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. type: YAML Front Matter: lang
+#: wiki/en/Adminstration.md:1
+#, no-wrap
+msgid "en"
+msgstr "de"
+
+#. type: YAML Front Matter: layout
+#: wiki/en/Adminstration.md:1
+#, no-wrap
+msgid "wiki"
+msgstr "wiki"
+
+#. type: YAML Front Matter: permalink
+#: wiki/en/Adminstration.md:1
+#, no-wrap
+msgid "/wiki/Adminstration"
+msgstr ""
+
+#. type: YAML Front Matter: title
+#: wiki/en/Adminstration.md:1
+#, no-wrap
+msgid "Adminstration"
+msgstr ""

translator-files/l10n/po/de/Central-Servers.po

@@ -0,0 +1,46 @@
+# SOME DESCRIPTIVE TITLE
+# Copyright (C) YEAR Free Software Foundation, Inc.
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"POT-Creation-Date: 2021-06-03 15:49+0200\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#. type: YAML Front Matter: category
+#: wiki/en/Central-Servers.md:1
+#, no-wrap
+msgid "hidden"
+msgstr ""
+
+#. type: YAML Front Matter: lang
+#: wiki/en/Central-Servers.md:1
+#, no-wrap
+msgid "en"
+msgstr "de"
+
+#. type: YAML Front Matter: layout
+#: wiki/en/Central-Servers.md:1
+#, no-wrap
+msgid "redirect"
+msgstr ""
+
+#. type: YAML Front Matter: permalink
+#: wiki/en/Central-Servers.md:1
+#, no-wrap
+msgid "/wiki/Central-Servers"
+msgstr ""
+
+#. type: YAML Front Matter: redirect
+#: wiki/en/Central-Servers.md:1
+#, no-wrap
+msgid "/wiki/Directory-Servers"
+msgstr ""