Documentation update: new translation process.

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

@@ -5,23 +5,6 @@ weight=20
 chapter=false
 +++
 
-Sie können uns helfen, dieses PeerTube-Plugin zu übersetzen, indem Sie Übersetzungsdateien im Ordner `languages` erstellen oder ändern.
+{{% notice warning %}}
-
+This page is not yet translated in your language, please refer to the english version. You can switch to it by using the language selector in the left menu.
-{{% notice tip %}}
-Bitte arbeiten Sie auf dem `main` Zweig, und machen Sie Ihre Änderungen und Pull Requests auf diesem Zweig.
 {{% /notice %}}
-
-{{% notice note %}}
-Until march 2023, contribution were made on the `develop` branch. This procedure is now deprecated.
-{{% /notice %}}
-
-Wenn die Sprache, für die Sie sich interessieren, noch nicht existiert, erstellen Sie eine Datei `code.json` im Ordner `languages`, wobei `code` der Code der Sprache ist.
-Der Sprachcode muss derselbe sein wie der Sprachcode von Peertube (siehe [Peertube-Dokumentation](https://github.com/Chocobozzz/PeerTube/blob/develop/support/doc/translation.md)).
-Fügen Sie dann die Sprachdatei in der Datei `package.json` unter dem Schlüssel `translations` hinzu.
-
-Die Übersetzungen werden wie folgt in der Sprachdatei festgelegt:
-
-- die Dateien sind im [JSON Format](https://www.json.org)
-- der JSON Schlüssel ist der englische Text (Siehe die bestehenden Schlüssel in der [französischen Übersätzungsdatei](languages/fr.json)).
-- der JSON Wert ist der übersätzte Text
-- Hinweis: Es gibt keine englische Übersätzungsdatei (So funktionieren Übersätzungen für Peertube Plugins)

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

@@ -5,55 +5,54 @@ weight=20
 chapter=false
 +++
 
-You can help us to translate this PeerTube plugin by creating or modifying translation files in the `languages` folder.
+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 info %}}
+{{% notice warning %}}
-For now, translation is done in the git repository. Later in 2023, online translation tools will be set (probably [Weblate](https://weblate.org)). This will make the translation process easier.
+Never modify directly files in the `languages` folder, this could lead to conflicts.
 {{% /notice %}}
 
-{{% notice tip %}}
+## How to
-Please work on the `main` branch, and do your commits and pull request on this branch.
-{{% /notice %}}
 
-{{% notice note %}}
+* Create an account: https://weblate.framasoft.org/accounts/register/
-Until march 2023, contribution were made on the `develop` branch. This procedure is now deprecated.
+* Validate your email and follow the link sent
-{{% /notice %}}
+* Create your password and setup your account
-
+* Go to the plugin project page: https://weblate.framasoft.org/projects/peertube-livechat/peertube-plugin-livechat/
-## Standard application strings
+* Choose the locale you want to translate
-
+* Just translate missing sentences, or correct the ones that seems incorrect to you.
-If the language you are interesting in does not exist yet, create a file `code.json` in the `languages` folder, where `code` is the language code.
-The language code must be the same as the Peertube's langage code (see [Peertube documentation](https://github.com/Chocobozzz/PeerTube/blob/develop/support/doc/translation.md)).
-Then add the language file in the `package.json` file, under the key `translations`.
-
-Translation strings are set in the language file as follow:
-
-- files are in [JSON format](https://www.json.org)
-- the JSON key is the english string (see existing keys in the [french translation file](languages/fr.json)).
-- the JSON value is the translating string
-- NB: there is no english translation file (this is how translation works for peertube's plugins)
-
-## Settings translations
-
-In the plugin settings page, there are more complex strings.
-They can be HTML code, with newlines, HTML tags, ...
-This is not suitable for the JSON format.
-
-That's why the process is a little bit different for settings strings.
-
-Settings strings are defined in [YAML files](https://en.wikipedia.org/wiki/YAML).
-They don't use the english text as key, but a codified key, like `list_rooms_label`.
-
-On the contrary of the standards application strings, there is also a configuration file for the english language.
-
-These files are in the folder `languages/settings`. If the file for the language that you are interested in does not exist, just create a new file
-named `code.yml`, where `code` is the language code (see above).
-
-Then, you can copy YAML keys from the reference file `languages/settings/en.yml`, and translate strings.
-
-If you don't want to translate a string, you can ignore it, or use `null` or `~` as value.
 
 {{% 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 %}}
+
+## Documentation translation
+
+Fow now, this is not done on Weblate. I still looking for the good technical solution.
+
+Please refer to the "documentation" documentation page.
+
+## 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.
+
+To use a string in front-end, you need (for now) to call `peertubeHelpers.translate` with the english string.
+This means we can't change english strings without updating the code.
+This is not optimal, but will change in a near future.
+
+For backend, for now the only file where there is localisation is
+`server/lib/settings.ts`. There is a `loc` function to call, passing as parameter the localisation key.
+
+If you have to test new strings without waiting for a Weblate merge, you can modify `languages/*.yml` files, but avoid to commit these change
+(to minimize conflict risks).

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

@@ -5,61 +5,23 @@ weight=20
 chapter=false
 +++
 
-Vous pouvez nous aider à traduire ce plugin Peertube en créant ou modifiant des fichiers de traduction dans le dossier `languages`.
+Vous pouvez contribuer à la traduction de ce plugin Peertube.
+Les traductions sont gérées par le logiciel [Weblate](https://weblate.org/),
+via [l'instance Weblate de Framasoft](https://weblate.framasoft.org/).
 
-{{% notice info %}}
+{{% notice warning %}}
-Pour le moment, les traductions se font directement dans le dépôt git.
+Ne modifiez jamais directement les fichiers dans le dossier `languages` du plugin,
-Plus tard en 2023, des outils de traduction en ligne seront mis en place
+vous risqueriez de créer des conflits.
-(probablement [Weblate](https://weblate.org)).
-Le processus de traduction en sera plus simple.
 {{% /notice %}}
 
-{{% notice tip %}}
+## Comment faire
-Merci de travailler sur la branche `main`, et de faire vos _pull request_ sur cette branche.
-{{% /notice %}}
 
-{{% notice note %}}
+* Créez-vous un compte: https://weblate.framasoft.org/accounts/register/
-Jusqu'à mars 2023, il fallait contribuer sur la branche `develop`. Cette procédure est désormais obsolète.
+* Validez votre email en cliquant sur le lien reçu
-{{% /notice %}}
+* Choisissez votre mot de passe, et configurez votre compte
-
+* Allez sur le projet du plugin de tchat: https://weblate.framasoft.org/projects/peertube-livechat/peertube-plugin-livechat/
-## Chaîne applicatives standard
+* Choisissez la langue que vous voulez traduire
-
+* Il ne vous reste plus qu'à ajouter les traductions manquantes, ou corriger celles qui vous semblent erronées.
-Si la langue dans laquelle vous souhaitez traduire n'existe pas encore, créez un fichier `code.json` dans le dossier `languages`, où `code` est le code langue.
-Le code langue doit être dans le même format que les codes langues de Peertube (voir la [documentation Peertube](https://github.com/Chocobozzz/PeerTube/blob/develop/support/doc/translation.md)).
-Ensuite, ajoutez le fichier de langue dans le fichier `package.json`, sous la clé `translations`.
-
-Les traductions sont sous la forme suivante dans le fichier de langue :
-
-- les fichiers sont au [format JSON](https://www.json.org)
-- les clés JSON sont le texte en anglais (voir les clés existantes dans [le fichier de traduction français](languages/fr.json), qui fait référence)
-- la valeur JSON est la traduction
-- NB: il n'y a pas de fichier de traduction pour l'anglais (c'est la façon de fonctionner de Peertube)
-
-## Traduction des paramètres du plugin
-
-Dans la page des paramètres du plugin, il y a des chaînes de texte plus compliquées.
-Elles peuvent contenir du code HTML, des retours à la ligne, ...
-Il est donc compliqué de les maintenir dans des fichiers JSON.
-
-C'est pourquoi le processus de traduction est différent pour les traductions de paramètres.
-
-Les traductions des paramètres sont définies dans des fichiers [YAML](https://fr.wikipedia.org/wiki/YAML).
-Elles n'utilisent pas l'anglais comme clé, mais des clés standardisées,
-comme par exemple `list_rooms_label`.
-
-Au contraire des chaînes applicatives standard, il y a aussi un fichier de
-configuration pour l'anglais.
-
-Ces fichiers sont dans le dossier `languages/settings`.
-Si le fichier de la langue qui vous intéresse n'existe pas, vous
-n'avez qu'à créer un fichier nommé `code.yml` où `code` est le code
-de la langue (voir plus haut).
-
-Ensuite, vous pouvez copier les clés du fichier HTML de référence
-`languages/settings/en.yml`, et traduire les chaînes de texte.
-
-Si vous ne voulez pas traduire une chaîne, vous pouvez l'ignorer,
-ou utiliser `null` ou `~` comme valeur.
 
 {{% notice warning %}}
 Il peut y avoir des chaînes «assez techniques».
@@ -67,3 +29,39 @@ Si vous n'êtes pas sûr⋅e à 100% du sens, ou de la traduction,
 il vaut mieux ne pas la traduire du tout ;
 ainsi la version anglaise s'affichera.
 {{% /notice %}}
+
+## Traduction de la documentation
+
+Pour l'instant, cela n'est pas encore géré dans Weblate. Je suis encore à la recherche de la bonne
+solution technique.
+
+Voir la page de documentation dédiée à la documentation.
+
+## Ajout d'une nouvelle langue
+
+Si la langue qui vous intéresse n'est pas présente, assurez-vous d'abord qu'elle est bien supportée par Peertube.
+Si c'est le cas, vous pouvez [ouvrir un ticket](https://github.com/JohnXLivingston/peertube-plugin-livechat/issues)
+pour en demander l'ajout.
+
+## Ajout de nouveau segment / utilisation dans le code
+
+Si vous travaillez sur une nouvelle fonctionnalité, et que vous avez besoin de nouveaux segments,
+créez les directement dans Weblate.
+La version anglaise est obligatoire, commencez par celle-ci.
+
+Chaque segment est lié à une clé (par exemple `use_chat`).
+Choisissez une clé en anglais, suffisamment explicite.
+
+Pour utiliser un segment coté front-end, il faut (pour l'instant), appeler `peertubeHelpers.translate`
+avec la version anglaise du texte. Attention, cela veut-dire qu'il faut éviter de changer un segment anglais
+existant.
+Cette solution n'est pas optimale, mais devrais bientôt changer.
+
+Coté backend, le seul endroit (pour l'instant) qui a besoin de localiser des choses, est la déclaration
+des settings du plugin.
+Il y a pour cela une fonction `loc` dédiée dans `server/lib/settings.ts` à appeler en lui fournissant
+la clé de la phrase à utiliser.
+
+Si vous avez besoin de tester vos localisations sans attendre la fusion venant de Weblate,
+vous pouvez modifier les fichiers `languages/*.yml`, mais évitez de les commit
+(pour minimiser le risque de conflits).