Merge pull request #248 from technosf/development

Development

Author: technosf

DEVELOP.md

@@ -19,9 +19,7 @@ Discover and Listen to your favourite internet radio stations, and add improve t
 
 ## Overview
 
-**_Tuner_** is hosted on [Github](https://github.com/louis77/tuner), packaged as a Flatpak and distributed by Flathub. **_Tuner_** is writen in [Vala](https://vala.dev/), a C#/Java/JavaFX-like language with a self-hosting compiler that generates C code and uses the GObject type system and wrapping a number of GTK libraries. It uses [Meson](https://mesonbuild.com/) as its build system.
-
-**_Tuner_** has not undergone a lot of attention in a while, and would benefit from a review with an eye to refactoring and cleaning up the code, while in the short term addressing known bugs and fixing basic functional issues, documentation and also making it easier to build and test.
+**_Tuner_** is hosted on [Github](https://github.com/tuner-app/tuner), packaged as a Flatpak and distributed by Flathub. **_Tuner_** is writen in [Vala](https://vala.dev/), a C#/Java/JavaFX-like language with a self-hosting compiler that generates C code, uses the GObject type system and wrapping a number of GTK libraries, and utilizes GNOME internationalization and localization (_i18n_) for user-facing strings, which are translated via [Weblate](https://hosted.weblate.org/projects/tuner/). [Meson](https://mesonbuild.com/) is the build system.
 
 ## Tuner Development
 
@@ -70,14 +68,14 @@ There are two build configurations: _debug_ and _release_. The _debug_ build (ma
 Clone the repo and drop into the Tuner directory:
 
 ```bash
-git clone https://github.com/louis77/tuner.git
+git clone https://github.com/tuner-app/tuner.git
 cd tuner
 ```
 
 Configure Meson for development debug build, build Tuner with Ninja, and run the result:
 
 ```bash
-meson setup --buildtype=debug builddir
+meson setup --buildtype=debug builddir -Dtranslate=update
 meson compile -C builddir
 meson install -C builddir     # only needed once to get the gschema in place
 ./builddir/com.github.louis77.tuner
@@ -135,7 +133,18 @@ Check the app version to ensure that it matches the version in the manifest.
 
 ### Build Changes
 
-If the build has changed it may be required to update repository check-in **Action** workflows in the _.github_ directory prior to check-in. For example if the _Platform_ chnges the Repository _Build and Test_ and _CI_ actions need to be updated. It is also good practice to check to see if the action components themselves have been superceded and need to reference new versions.
+If the build has changed it may be required to update repository check-in **Action** workflows in the _.github_ directory prior to check-in. For example if the _Platform_ chnges the Repository _Build and Test_ and _CI_ actions need to be updated and pushed prior to code changes are pushed. It is also good practice to check to see if the action components themselves have been superceded and need to reference new versions.
+
+### Language Changes & Translations
+
+Changes to strings that are internationalized require translation via [Weblate](https://hosted.weblate.org/projects/tuner/) and reintegration of the new translations into the build.
+
+for translation by GNOME gettext require that the _.pot_ file be regenerated, checked in and pushed so
+
+```bash
+meson compile -C builddir pot
+meson compile -C builddir extra-pot
+```
 
 ### Code Changes
 
@@ -212,7 +221,7 @@ After checking out the required version, build and run the app as described abov
 
 ## Release Process
 
-Releasing _Tuner_ comprises cutting a release of the code in [tuner github](https://github.com/louis77/tuner) and then updating the [flathub repo](https://github.com/flathub/com.github.louis77.tuner) which will automatically have the flatpak generated and rolled to Flathub for distribution.
+Releasing _Tuner_ comprises cutting a release of the code in [tuner github](https://github.com/tuner-app/tuner) and then updating the [flathub repo](https://github.com/flathub/com.github.louis77.tuner) which will automatically have the flatpak generated and rolled to Flathub for distribution.
 
 ### Beta Releases
 

I18N.md

@@ -0,0 +1,42 @@
+# Internationalization
+
+**Tuner** uses [Gnome *i18n*](https://developer.gnome.org/documentation/guidelines/localization.html) for internationalization. This system specifies target files and extracts identified strings for translation in the source, the target languages, and during the build process compiles translated strings into package which. The appropriate translated strings are then used by the host system when running **Tuner**.
+
+Translations are managed and applied by [Weblate](https://hosted.weblate.org/projects/tuner/) as two different components:
+
+* The application [UI](https://hosted.weblate.org/projects/tuner/tuner-ui/)
+* The flatpak [Desktop](https://hosted.weblate.org/projects/tuner/tuner-desktop/) metadata
+
+As languages and translations are updated in Weblate, Weblate generates the approriate Gnome *.po*  translations files and opens pull requests on **Tuner**.
+
+## Translate and add languages
+
+Anyone with a [Weblate account](https://hosted.weblate.org/) can view the current [Tuner](https://hosted.weblate.org/projects/tuner/) translations and add or correct them.
+
+[![Translation status](https://hosted.weblate.org/widget/tuner/multi-auto.svg)](https://hosted.weblate.org/engage/tuner/)
+
+## i18n in the code
+
+Strings in the UI source code that are candidates for translation are identifed using the standard Gnome *xgettext* identification by being encapsulated by *\_()*
+
+Build files to create the translation instructions (*.pot* files), translations (*.po* files) and resulting files themselves exist in the *po* directory. These files do not need to be generated very frequently - only after source strings have changed, or new translations created, and prior to packaging the app.  
+
+Weblate picks up source string changes from the Tuner *development* branch *.pot* files. New translations (*.po* files) arive in the directories via *pull requests* from Weblate to the Tuner repo development branch.
+
+The *.pot* files are build by *xgettext* scanning the files specified in *POTFILES*. To regenrate the *.pot* files requires a build:
+
+```bash
+rm -r builddir
+meson setup --buildtype=debug builddir -Dtranslation=update
+meson compile -C builddir pot
+meson compile -C builddir extra-pot
+```
+
+This:
+
+* Removes the current build directory
+* Regenerates the build directory with the flag set to update the translations
+* Builds the **main** *.pot* file that relates to the UI
+* Builds the **extra** *.pot* file that relates to the Desktop metadata
+
+Updates to the *.pot*, *LINGUAS* and *POTFILES* files *pushed* to the development branch will be picked up by Weblate and can be worked on on the Weblate **Tuner** page.

NOTES.md

@@ -1,5 +1,41 @@
 # Packaging instructions for various platform
 
+## Local Build
+
+Building Tuner localy is described in the [development doc](DEVELOP.md).
+
+## Packages for other platforms and distos
+
+Other packed versions of Tuner are available, but are maintained outside of Tuner itself: Versions may be out of date.
+
+### Arch Linux / AUR
+
+Arch-based GNU/Linux users can find `Tuner` under the name [tuner-git](https://aur.archlinux.org/packages/tuner-git/) in the **AUR**:
+
+```bash
+yay -S tuner-git
+```
+
+Thanks to [@btd1377](https://github.com/btd1337) for supporting Tuner on Arch Linux!
+
+### MX Linux
+
+MX Linux users can find `Tuner` by using the MX Package Installer (currently under the MX Test Repo tab for MX-19 and the Stable Repo for MX-21)
+
+Thanks to SwampRabbit for packaging Tuner for MX Linux!
+
+### Pacstall
+
+Pacstall is a totally new package manager for Ubuntu that provides an AUR-like community-driven repo for package builds. If you already use `pacstall` you can install Tuner:
+
+```bash
+pacstall -I tuner
+```
+
+If you have Ubuntu and want a clean build of Tuner on your system, consider using `pacstall` instead of Flatpak if you don't feat beta software. Get `pacstall` here:
+
+<https://pacstall.dev>
+
 ## General
 
 ### Desktop Menu