Documentation translation (#199)

Documentation translation using weblate.

* Use po4a to generate .po files from the english markdowns, then to generate translated files
* Some pages can be marked as «english only» (for technical documentation for example)
* New Hugo shortcode to use application strings in documentation (for example for settings names)
* The code of conduct is no more translated, but there is a link to official Contributor Covenant translations
* Adding all plugin's supported languages

Related to https://github.com/JohnXLivingston/peertube-plugin-livechat/issues/117

support/documentation/content/en/contributing/_index.md

@@ -0,0 +1,10 @@
+---
+title: "Contributing"
+description: "Contributing"
+weight: 60
+chapter: false
+---
+
+Interested in contributing? Awesome!
+
+{{% children style="li" depth="3" description="true" %}}

support/documentation/content/en/contributing/codeofconduct/_index.md

@@ -0,0 +1,14 @@
+---
+title: "Code of Conduct"
+description: "Contributor Covenant Code of Conduct"
+weight: 10
+chapter: false
+---
+
+{{% notice tip %}}
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement by mail at git.[at].john-livingston.fr.
+{{% /notice %}}
+
+{{% livechat_codeofconduct %}}

support/documentation/content/en/contributing/develop/_index.md

@@ -0,0 +1,140 @@
+---
+title: "Develop"
+description: "Develop"
+weight: 40
+chapter: false
+---
+
+Always talk about features you want to develop by creating/finding and commenting the issue tackling your problem
+before you start working on it, and inform the community that you begin coding by claiming the issue.
+
+Pull Request must be done on the `main` branch.
+
+{{% notice note %}}
+Until march 2023, contribution were made on the `develop` branch. This procedure is now deprecated.
+{{% /notice %}}
+
+Prerequisite for building this plugin:
+
+- you must have `npm` installed
+- you must have python venv installed (`python3-venv` package on Debian for example)
+- you must have `build-essential` installed
+
+To clone the repository:
+
+```bash
+# Clone the repository. Dont forget the --recursive to clone submodules.
+git clone https://github.com/JohnXLivingston/peertube-plugin-livechat.git --recursive
+
+# Install NPM dependencies and build the module for the first time:
+npm install
+
+# Build the plugin after a modification:
+npm run build
+
+# If you have a fork from the repository, add it as remote (example):
+git remote add me git@github.com:MY_GITHUB_ACCOUNT/peertube-plugin-livechat.git
+
+# Create a local branch for you developments, and checkout it (example):
+git checkout my_development # Note: if an issue is associated, use fix_1234 as your branch name (where 1234 is the issue's number)
+# To propose your modifications, push your branch to your repository (example):
+git push --set-upstream me my_development
+# Then go to your github repository with your web browser to propose the Pull Request (see additional instructions below)
+```
+
+Once you are ready to show your code to ask for feedback, submit a *draft* Pull Request.
+Once you are ready for a code review before merge, submit a Pull Request. In any case, please
+link your PR to the issues it solves by using the GitHub syntax: "fixes #issue_number".
+
+The front-end code is in the `client` folder, the back-end code in `server`. There are some shared code in `shared` folder.
+
+For general instructions (developping plugins, building, installation, ...), please refer to the [Peertube documentation](https://docs.joinpeertube.org/contribute-plugins?id=write-a-plugintheme).
+
+You can build the plugin with extra debug features simply by using:
+
+```bash
+NODE_ENV=dev npm run build
+```
+
+## ESBuild vs Typescript
+
+This plugin uses ESBuild for frontend code generation, as the official `peertube-plugin-quickstart` plugin.
+ESBuild can handle Typescript, but does not check types
+(see [ESBuild documentation](https://esbuild.github.io/content-types/#typescript)).
+That's why we first compile Typescript with the `-noEmit` option, just to check types (`check:client:ts` in package.json file).
+Then, if everything is okay, we run ESBuild to generate the compiled javascript.
+
+## Debug Mode
+
+There is a debug mode for this plugin, that shorten some delay.
+For example, some log files will rotate every two minutes, instead of once per day.
+This permit to test more easily certain actions, for which it could normally take hours or days to wait.
+
+To enable this mode, you juste have to create the
+`/var/www/peertube/storage/plugins/data/peertube-plugin-livechat/debug_mode` file
+(replacing `/var/www/peertube/storage/` by the correct path on your installation).
+
+The simple existence of this file is sufficient to trigger the debug mode.
+To make sure it's taken into account, you can restart your Peertube instance.
+
+This file can contain some JSON to enable more advanced options.
+To have a list of existing parameters, check `server/lib/debug.ts`.
+Restart Peertube after each content modification.
+
+{{% notice warning %}}
+Don't enable this mode on a production server, neither on a public server.
+This could cause security issues.
+{{% /notice %}}
+
+### Restart Prosody
+
+When debug mode is enabled, you can restart Prosody using this API call:
+`http://your_instance.tld/plugins/livechat/router/api/restart_prosody`.
+This call don't need any authentificaiton.
+It can be done from a command line, for example using
+`curl http://your_instance.tld/plugins/livechat/router/api/restart_prosody`.
+
+### Prosody debugger
+
+It is possible to connect the Prosody AppImage to a remote debugger using [MobDebug](https://luarocks.org/modules/paulclinger/mobdebug).
+
+To do so, you have to setup MobDebug in a folder that can be accessed by the `peertube` user.
+Then, add this in the `debub_mode` file:
+
+```json
+{
+  "debug_prosody": {
+    "debugger_path": "/the_path_to_mobdebug/src",
+    "host": "localhost",
+    "port": "8172"
+  }
+}
+```
+
+`host` and `port` are optional. `debugger_path` must point to the folder where the `MobDebug` `.lua` file is.
+
+Restart Peertube.
+
+Start your debugger server.
+
+For Prosody to connect to the debugger, call the API
+`http://your_instance.tld/plugins/livechat/router/api/restart_prosody?debugger=true`.
+This call does not need any authentication.
+It can be done from a command line, for example with
+`curl http://your_instance.tld/plugins/livechat/router/api/restart_prosody?debugger=true`.
+You can even configure your debug server to launch this request automatically.
+
+Prosody will then restart, connecting to the debugger.
+
+## Quick dev environment using Docker
+
+There is a tutorial, in french, on the
+[le Peertube forum](https://framacolibri.org/t/tutoriel-creer-un-environnement-de-developpement-de-plugin-peertube-rapidement-en-utilisant-docker-et-qui-permet-de-tester-la-federation/17631)
+that explains how to quickly build a dev env using Docker.
+
+A repo was made out of it, check out [pt-plugin-dev](https://codeberg.org/mose/pt-plugin-dev).
+
+Note: for an unknown reason, Prosody can't resolve containers DNS address when using the lua-unbound library.
+There is a dirty hack in the plugin: just create a
+`/data/plugins/data/peertube-plugin-livechat/no_lua_unbound` file in your docker-volumes,
+then restart containers.

support/documentation/content/en/contributing/document/_index.md

@@ -0,0 +1,98 @@
+---
+title: "Documentation"
+description: "Document the plugin, or translate the documentation."
+weight: 50
+chapter: false
+---
+
+## General information
+
+Always inform the community before working (by creating a new issue, or commenting an existing one).
+This is to avoid that two persons are working on the same thing, and prevent conflicts.
+
+Documentation work has to be merged in the `main` branch.
+
+The documentation source code is in the `support/documentation/content` folder.
+
+The documentation is generated using [Hugo](https://gohugo.io/).
+You have to install it on your computer if you want to preview your work.
+
+The used theme is [hugo-theme-learn](https://learn.netlify.app/).
+You should read its documentation before starting editing the documentation.
+
+When a new plugin version is released, or when documentation is updated, plugin maintainers will merge the `main` branch to the `documentation` branch.
+This will trigger github and gitlab pipelines, and update published documentation.
+
+## Translations
+
+The principal language is english (`en` code).
+
+The `support/documentation/content/en` folder contains only english documentation files.
+
+Documentation is translated using Weblate (see the [translation documentation](/peertube-plugin-livechat/contributing/translate/)).
+To do so, we use the [po4a tool](https://po4a.org/), as we will se later in this page.
+
+## Add a new language
+
+In the `support/documentation/config.toml` file, please copy and modify the `[Languages.fr]` section.
+
+If the translations are not complete, it does not matter, english will be used for missing strings.
+
+## Preview
+
+To preview your modifications, just run:
+
+```bash
+hugo serve -s support/documentation/
+```
+
+Then open your browser on the address [http://localhost:1313/peertube-plugin-livechat/](http://localhost:1313/peertube-plugin-livechat/).
+This page will automatically refresh on each modification.
+
+## Update localization files and generate documentation translations
+
+For now, you only have the english version.
+To update documentation strings, and generate translations, you have to run the `doc-translate.sh` script.
+
+To do so, make sure you have `po4a` (version >= 0.66) installed on your computer.
+
+{{% notice warning %}}
+Some linux distro (like Debian Bullseye for example) have too old version of `po4a`.
+Please make sure to install a compatible version.
+If you are using Debian Bullseye for example, you can download the Bookwork po4a.deb file from https://packages.debian.org, and install it manually.
+{{% /notice %}}
+
+To handle translations, just do:
+
+```bash
+npm run doc:translate
+```
+
+You can then preview the result using `hugo serve -s support/documentation/`, and using the language selector.
+
+## Write documentation
+
+Just edit the english files in `support/documentation/content/en`.
+
+Then, before commiting, always run `npm run doc:translate`, so that changes in english files can be propagated to the `support/documentation/po/livechat.en.pot` file.
+
+You can use the `livechat_label` short code to use application strings.
+See here: [Documentation translation](/peertube-plugin-livechat/contributing/translate/#documentation-translation).
+
+It is possible to prevent a file from beeing translating, using `livechatnotranslation: true` in the Yaml Font Matter section.
+See here: [Documentation translation](/peertube-plugin-livechat/contributing/translate/#documentation-translation).
+
+Please use the `livechatnotranslation` option for technical documentation.
+We don't want technical documentation to be translated, to avoid issues because of a wrong translation.
+
+Avoid adding line breaks in middle of a sentence.
+But add a line break after each sentence in a paragraph.
+This is to facilitate the work for translators: so then can easily check that they don't miss a sentence when translating a parapraph.
+
+### What if I can't use hugo and/or po4a?
+
+Just edit english markdown files, and specify that you can't build translations when you make your Pull Request.
+
+## Publication
+
+Publishing the documentation is automatic, as soon as the changes are merged into the `documentation` branch.

support/documentation/content/en/contributing/feedback/_index.md

@@ -0,0 +1,9 @@
+---
+title: "Give your feedback"
+description: "Give your feedback"
+weight: 30
+chapter: false
+---
+
+You don't need to know how to code to start contributing to this plugin!
+Other contributions are very valuable too, among which: you can test the software and report bugs, you can give feedback, features that you are interested in, user interface, design, ...

support/documentation/content/en/contributing/translate/_index.md

@@ -0,0 +1,112 @@
+---
+title: "Translate"
+description: "Translate the plugin"
+weight: 20
+chapter: false
+---
+
+You can contribute to this plugin translation.
+Translations are handled using the [Weblate](https://weblate.org/) software,
+using [Framasoft Weblate instance](https://weblate.framasoft.org/).
+
+{{% notice warning %}}
+Never modify directly files in the `languages` folder, this could lead to conflicts.
+{{% /notice %}}
+
+## How to
+
+* Create an account: https://weblate.framasoft.org/accounts/register/
+* Validate your email and follow the link sent
+* Create your password and setup your account
+* Go to the plugin project page: https://weblate.framasoft.org/projects/peertube-livechat/peertube-plugin-livechat/
+* Choose the locale you want to translate
+* Just translate missing sentences, or correct the ones that seems incorrect to you.
+
+{{% notice warning %}}
+There might be some «very technical» strings. If you are not 100% sure of
+the meaning, or of your translation, you better not translate it,
+so it will display in english.
+{{% /notice %}}
+
+## Adding a new locale
+
+If you think there is a missing locale, please check first if it is handled in Peertube.
+If so, you can [open an issue](https://github.com/JohnXLivingston/peertube-plugin-livechat/issues) to ask for it.
+
+## Adding new strings / use translations in the code
+
+If you are working on new features, and need new strings, you can create them directly in Weblate.
+The english version is mandatory. Start with it.
+
+Each string is linked to a key (for example `use_chat`).
+Choose an explicit key in english, lower case.
+
+If you have to test new strings without waiting for a Weblate merge, you can modify `languages/*.yml` files,
+but avoid to commit these changes (to minimize conflict risks).
+
+### Use translations in front-end code
+
+Before using a string in front-end, you need to declare a new constant in `client/@types/global.d.ts`.
+The constant name must:
+
+* start with the prefix "LOC_"
+* use the string key, upper cased
+* you just have to declare its type, not its value
+
+For example, to use "use_chat", you have to declare:
+
+```typescript
+declare const LOC_USE_CHAT: string
+```
+
+The `build-client.js` script will read the `client/@types/global.d.ts`,
+search for such constants, and load their values from the languages files.
+
+Now, you can simply call `peertubeHelpers.translate(LOC_USE_CHAT)` in your code.
+
+### Use translations in back-end code
+
+In theory, the only parts of the backend code where you need localization is the
+settings declaration and standardized data (ActivityPub, RSS, ...).
+Here we need to get english strings from the translation key.
+
+Note: you should never need another language translation from backend code.
+Localization must be done on front-end.
+
+There is a `lib/loc.ts` module providing a `loc()` function.
+Just pass it the key to have the english string: `loc('diagnostic')`'.
+
+## Documentation translation
+
+The documentation translation is done using the corresponding Weblate component.
+
+There is a specific "Hugo shortcodes" you can use to display an application string.
+Saying you want to display the name of the button "open_chat_new_window", you can use this in the documentation markdown file:
+
+```hugo
+{{%/* livechat_label open_chat_new_window */%}}
+```
+
+You can also prevent a whole page from being translating by adding `livechatnotranslation: true` in the Yaml Font Matter section:
+
+```yaml
+---
+title: "Third party"
+description: "Displaying the livechat with 3rd party software."
+weight: 20
+chapter: false
+livechatnotranslation: true
+---
+```
+
+Never translate a string in the `livechat.en.pot` file, it would be ignored.
+Instead, edit directly the markdown files.
+
+If a string contains a link, you can change it for the correct link in the translated language.
+For example, for a link to this documentation, you can add the language code in the url.
+
+Some strings are block of code.
+Don't translate code.
+But you can translate comments, or parameters if relevant.
+
+If you are not sure, just don't translate, and ask what to do.