Merge pull request #2880 from ann0see/documentWeblate

jamulussoftware · Oct 20, 2022 · 1820d66 · 1820d66
2 parents 4c2cdba + ac72fd5
commit 1820d66
Show file tree

Hide file tree

Showing 3 changed files with 85 additions and 34 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -87,7 +87,7 @@ The ChangeLog must be updated for each new feature or bug fix. Please include a
 
 If you are a first-time contributor/translator, please add your name to the contributors/translators list in the About dialog of Jamulus (see in `src/util.cpp` in the constructor function `CAboutDlg::CAboutDlg()`).
 
-### Merging Pull Requests
+### Merging pull requests
 
 The git master branch is protected and requires at least two reviews by the main developers before the pull request can be merged. Any of the main developers can initiate the merge if a pull request receives at least two positive reviews.
 

diff --git a/docs/TRANSLATING.md b/docs/TRANSLATING.md
@@ -2,26 +2,42 @@
 
 This guide is written to provide instructions from scratch for contributing to the translation of the Jamulus application to other languages.
 
-The code for Jamulus is open source, and is managed and made available via the Github site.
+Jamulus is mostly developed on GitHub. However, translators are not required to use GitHub, as Jamulus is translated on [Hosted Weblate](https://hosted.weblate.org/projects/jamulus/).
 
-For completeness, this document describes the use both of GitHub (using `git`) and of _Qt Linguist_.
+You have two options to translate Jamulus:
+1. Using [Weblate](https://hosted.weblate.org/projects/jamulus/jamulus-app/) (online translation, easier and more feature rich. However, as of 10/2022, it will show your e-mail address on GitHub.) (recommended)
+2. Using Git directly (more advanced, but you can test your changes on your machine locally)
 
 ---
 
-## Introduction
+## Introduction (using Weblate)
 
-The translator must be able to do the following steps, which will each be explained further down:
+Translators should (if possible) have a GitHub account to communicate, as described in the **1. Setting up** paragraph in the Git section below. This account should be used to [create an account on Hosted Weblate](https://hosted.weblate.org/accounts/register/). Ensure that the Jamulus main developers are aware of your intentions to translate to your chosen language beforehand (e.g. by [creating or commenting on a respective issue during the release process for your language on GitHub](https://github.com/jamulussoftware/jamulus/issues)). This ensures you will have proper access and that support is provided. Have a look at the [adding a new language (checklist)](#adding-a-new-language-checklist) for what to expect.
+
+## Using Weblate for translation
+
+After logging into Hosted Weblate, visit the [Jamulus project page on Hosted Weblate](https://hosted.weblate.org/projects/jamulus/). There are several components dedicated to the Jamulus project. If you want to translate e.g. the main Jamulus program or the Windows installer, click on "[Jamulus app](https://hosted.weblate.org/projects/jamulus/jamulus-app/)" or "[Windows Installer](https://hosted.weblate.org/projects/jamulus/windows-installer/)" and choose your language. After that, translate the strings displayed on the Website. Weblate will open or update a pull request on the Jamulus repo within the next few hours, where your translation will be reviewed.
+
+More info is provided in the [Weblate documentation](https://docs.weblate.org/).
+
+---
+
+## Introduction (using Git)
+
+For completeness, this document describes the use of both GitHub (using Git), and of _Qt Linguist_.
+
+The translator must be able to carry out the following steps, each of which are explained below:
 
 - Create their own linked copy ("repository" or "repo") of Jamulus in GitHub. This is called Forking.
 - Copy ("clone") their own repository to their computer, using either:
   - Command line `git`, or
-  - [Github Desktop](https://docs.github.com/en/desktop)
+  - [GitHub Desktop](https://docs.github.com/en/desktop)
 - Update their own local repo from the upstream master branch.
 - Create a local branch to contain the update.
 - Use the Qt Linguist tool to edit the appropriate translation (`.ts`) file.
 - Commit the updated `.ts` file to the branch their own local git repo.
-- Push the branch from their local repo to their own repo on Github.
-- Raise a Pull Request (PR) for the merging of the updated file into the upstream repo by the developers.
+- Push the branch from their local repo to their own repo on GitHub.
+- Open a pull request (PR) the developers can use to merge the updated file into the upstream repo.
 
 This guide contains two main parts:
 
@@ -35,22 +51,22 @@ This guide contains two main parts:
 
 ### Visit github.com
 
-First of all, visit the [Github website](https://github.com)
+First of all, visit the [GitHub website](https://github.com)
 
-If you don't yet have a Github account, click on **Sign up** to go to the Create Your Account page. Enter:
+If you don't yet have a GitHub account, click on **Sign up** to go to the Create Your Account page. Enter:
 
-- Your chosen username. This is a simple word containing letters and, optionally, numbers, and will identify you in the Github world. It is not an email address. This name is represented in the examples below as `yourusername`.
-- Your email address. This will be used by Github to send you notifications by email, and to identify commits made by you.
+- Your chosen username. This is a simple word containing letters and, optionally, numbers, and will identify you in the GitHub world. It is not an email address. This name is represented in the examples below as `yourusername`.
+- Your email address. This will be used by GitHub to send you notifications by email, and to identify commits made by you.
 - Your chosen password. Do not use the same password as for any other website.
 - Solve the puzzle to prove you are human and click **Create account**.
 
-If you do have a Github account, and are not yet logged in, click on **Sign in**, and enter your username and password, then **Sign in**.
+If you do have a GitHub account, and are not yet logged in, click on **Sign in**, and enter your username and password, then **Sign in**.
 
 Go to the [Jamulus repository](https://github.com/jamulussoftware/jamulus).
 
 Create your own copy ("fork") of the Jamulus repository by clicking the **Fork** button at the top right of the page.
 
-If your Github account is also part of an organisation, Github will ask you where to create the fork. Choose your personal Github account.
+If your GitHub account is also part of an organisation, GitHub will ask you where to create the fork. Choose your personal GitHub account.
 
 It will then display the message "Forking jamulussoftware/jamulus", and when finished will display the home page of your own Jamulus repo (**yourusername/jamulus**).
 
@@ -91,20 +107,20 @@ This will create a `jamulus` directory. Change to that directory.
   upstream        https://github.com/jamulussoftware/jamulus.git (push)
   ```
 
-### Github Desktop
+### GitHub Desktop
 
-[Github Desktop](https://docs.github.com/en/desktop) is available for macOS 10.10 or later, and Windows 7 64-bit or later. It is not available for 32-bit Windows.
+[GitHub Desktop](https://docs.github.com/en/desktop) is available for macOS 10.10 or later, and Windows 7 64-bit or later. It is not available for 32-bit Windows.
 
-To install Github Desktop, visit the [download page](https://desktop.github.com) and follow the link for the appropriate Operating System.
+To install GitHub Desktop, visit the [download page](https://desktop.github.com) and follow the link for the appropriate Operating System.
 
 When downloading for Mac, the instructions suggest opening `GitHubDesktop.zip`, but in fact, what was downloaded was `GitHubDesktop.app`. This should just be moved from `Downloads` to `Applications`.
 
-Run Github Desktop, and do the following steps:
+Run GitHub Desktop, and do the following steps:
 
-- On the Welcome Screen, click on **Sign in to GitHub.com**
-- Sign in by following the instructions. These may vary depending on whether you have logged into Github via a web browser already. If necessary, click on **Authorize Desktop**.
-- Confirm access by entering your Github password.
-- for Mac, if the browser requests to open "Github Desktop.app", click **Allow**.
+- On the Welcome Screen, click on **Sign in to github.com**
+- Sign in by following the instructions. These may vary depending on whether you have logged into GitHub via a web browser already. If necessary, click on **Authorize Desktop**.
+- Confirm access by entering your GitHub password.
+- for Mac, if the browser requests to open "GitHub Desktop.app", click **Allow**.
 - In Configure Git, enter your name and email address. These will be used to identify commits you make to Git. Click **Continue**.
 - Agree or decline to submit periodic usage stats, and click **Finish**.
 - Either:
@@ -161,9 +177,9 @@ git checkout -b translate-r3_7_0-german
 
 (The branch name is chosen by the user; the above name translate-r3_7_0-german is an example for the German translation of V3.7.0)
 
-The branch will be used later as the source of a Pull Request.
+The branch will be used later as the source of a pull request.
 
-#### With Github Desktop
+#### With GitHub Desktop
 
 Select the current repository as `jamulus`, and the current branch as `master`.
 
@@ -193,9 +209,9 @@ Again, strings with a question mark require translation.
 
 After some or all of the required strings have been translated, the file can be saved.
 
-### Submit the updated translation as a Pull Request (PR)
+### Submit the updated translation as a pull request (PR)
 
-Once all translations have been done, the branch containing the changes must be commited to your own repo, pushed to Github (`origin`) and then a Pull Request raised to the upstream repo.
+Once all translations have been done, the branch containing the changes must be commited to your own repo, pushed to GitHub (`origin`) and then a pull request raised to the upstream repo.
 
 #### With git command line tools
 
@@ -214,9 +230,9 @@ It will probably tell you to set the upstream repository for tracking, and conve
 git push --set-upstream origin translate-r3_7_0-german
 ```
 
-Finally, go to the Github website where it will most likely offer a banner saying there is a recent commit and offering to raise a Pull Request. Do so.
+Finally, go to the GitHub website where it will most likely offer a banner saying there is a recent commit and offering to open a pull request. Do so.
 
-#### With Github Desktop
+#### With GitHub Desktop
 
 Select the current repository as `jamulus`, and the branch that was created above, such as `translate-r3_7_0-german`.
 
@@ -227,9 +243,9 @@ to something like "Update German translations for v3.7.0"), and add any extra de
 
 Commit the changes to the local git repo by clicking on **Commit to <branch>**.
 
-Click on **Publish branch** or **Push origin**. This will push the branch to your own repo on Github. (It will say **Publish branch** for a new branch, or **Push origin** if the branch has already been published).
+Click on **Publish branch** or **Push origin**. This will push the branch to your own repo on GitHub. (It will say **Publish branch** for a new branch, or **Push origin** if the branch has already been published).
 
-There will now be a section offering **Create Pull Request**. Click on that to create the PR to the upstream repository.
+There will now be a section offering **Create pull request**. Click on that to create the PR to the upstream repository.
 
 #### Updating a PR/fixing conflicts
 
@@ -246,6 +262,39 @@ git push --force # Push the changes to your repo. Be aware that this will overwr
 
 ---
 
+## Adding a new language (checklist)
+
+The following section describes how to add a new language and what to do or wait for.
+Please open an issue on GitHub and introduce yourself first, even if you intend to add the translation files yourself.
+
+After having opened an issue on GitHub:
+1. Fork the Jamulus repository as described above, then install Qt on your machine (See [COMPILING.md](../COMPILING.md)). (You will need `lrelease` and `lupdate` later on.)
+2. Create a branch based on the `master` branch: Locally navigate to the folder you cloned the repo to (with `cd /path/to/jamulus/repo`) and type `git checkout -b "translate-add-xx_YY"` (where xx_YY is the language code of the new language).
+3. Open Jamulus.pro in an editor such as `nano`: `nano Jamulus.pro` and add your language file (which will be created later) in alphabetical order to the `TRANSLATIONS` variable. The format should match the other present languages.
+4. Also add `src/translation/translation_xx_YY.qm` to the DISTFILES variable similar to the other files
+5. Save and close Jamulus.pro.
+6. Add the `.qm` file in `src/resources.qrc` similar to other languages.
+7. Now move back to the repository root and run `lupdate Jamulus.pro`. Afterwards, run `lrelease Jamulus.pro` which should create all of the necessary files.
+8. Finally, add, commit and push the changes to your repository with the following commands: `git add Jamulus.pro src/translation/translation_xx_YY.* src/resources.qrc`, `git commit -m "Translation: Add empty xx_YY translation"`, `git push`
+9. Open a pull request from your repo to the main repo with a brief description that you plan to translate Jamulus to your language
+10. Once the pull request is merged, Weblate should pick up the new language.
+
+### Adding a translation to the Windows installer
+
+To add a new translation to the Installer (while undertaking the above steps with Git) [as described above](#adding-a-new-language-checklist):
+
+1. Copy `src/translation/wininstaller/en_UK.nsi` to `src/translation/wininstaller/xx_YY.nsi`
+2. Add your language with [the correct language code](https://nsis.sourceforge.io/Examples/Modern%20UI/MultiLanguage.nsi) to `src/translation/installerlng.nsi` by following the file format
+3. Rename `${LANG_ENGLISH}` to the respective value you set in installerlng.nsi in xx_YY.nsi
+
+### After a language is added
+
+Start translating the new language using Hosted Weblate or Git (as described in the first section of this guide). If you plan to work on the translation for a longer period, please contact the administrators to be invited to the Jamulus organisation as well as translators channel on Discord or Matrix.
+
+Since every contributor can and should be added to the in-app contributor list, please remind us to add you to the `src/utils.h` file as translator or open a pull request yourself.
+
+---
+
 ## That's all
 
 Thank you for contributing!
diff --git a/tools/create-translation-issues.sh b/tools/create-translation-issues.sh
@@ -68,7 +68,7 @@ We are getting ready for the ${RELEASE} release. No further changes to translata
 
 We would be happy if you updated the Jamulus software translations for **${LANG}** by **${DEADLINE}**.
 
-Please
+Please either [update the translations on Hosted Weblate](https://hosted.weblate.org/projects/jamulus/) or use Git:
 - Update your fork from `jamulussoftware/jamulus` `master` and create a working branch
 - Update translations using Qt Linguist in your fork,
 - Commit and push your changes and reference this Issue,
@@ -85,7 +85,9 @@ ${EXTRA_TEXT}${MULTIPLE_TRANSLATORS_TEXT}
 
 Further documentation can be found in [TRANSLATING.md](https://github.com/jamulussoftware/jamulus/blob/master/docs/TRANSLATING.md).
 
-Thanks for contributing to Jamulus!'
+Thanks for contributing to Jamulus!
+
+<a href="https://hosted.weblate.org/engage/jamulus/"><img src="https://hosted.weblate.org/widgets/jamulus/-/jamulus-app/multi-auto.svg" alt="Translation status" /></a>'
 
 # shellcheck disable=SC2016  # shellcheck can't know that this will be used with envsubst, so verbatim variables are correct here.
 BODY_TEMPLATE_WEB='Hi ${SPLIT_TRANSLATORS},
@@ -94,10 +96,10 @@ We are getting ready for the ${RELEASE} release and have created the [${TRANSLAT
 
 We would be happy if you updated the translations for **${LANG}** by **${DEADLINE}**.
 
-Please
+Please either [update the translations on Hosted Weblate](https://hosted.weblate.org/projects/jamulus/), or use Git:
 
 - Start your work in your fork on a branch based on jamuluswebsite'"'"'s `${TRANSLATE_BRANCH}` branch.
-- Update the language-specific files using your favorite editor (or directly on Github),
+- Update the language-specific files using your favourite editor (or directly on GitHub),
 - New/changed images are listed at the end of this issue. [Generate new URLs](https://github.com/jamulussoftware/jamuluswebsite/tree/release#adding-screenshots) for your image `.inc` files.
 - Commit and push your changes to your fork,
 - Open a Pull Request with your translations to the **${TRANSLATE_BRANCH}** branch with the subject `${TITLE}`,