From aeb3c76b697c0de05d75ac4d0ef637c8f78241b3 Mon Sep 17 00:00:00 2001 From: John Livingston Date: Fri, 9 Jun 2023 18:31:48 +0200 Subject: [PATCH] Documentation update: new translation process. --- .../contributing/translate/_index.de.md | 21 +--- .../contributing/translate/_index.en.md | 83 +++++++-------- .../contributing/translate/_index.fr.md | 100 +++++++++--------- 3 files changed, 92 insertions(+), 112 deletions(-) diff --git a/support/documentation/content/contributing/translate/_index.de.md b/support/documentation/content/contributing/translate/_index.de.md index 6d3c4dc8..f3119d07 100644 --- a/support/documentation/content/contributing/translate/_index.de.md +++ b/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 tip %}} -Bitte arbeiten Sie auf dem `main` Zweig, und machen Sie Ihre Änderungen und Pull Requests auf diesem Zweig. +{{% 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 %}} - -{{% 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) \ No newline at end of file diff --git a/support/documentation/content/contributing/translate/_index.en.md b/support/documentation/content/contributing/translate/_index.en.md index 8e240254..3d46a5d8 100644 --- a/support/documentation/content/contributing/translate/_index.en.md +++ b/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 %}} -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. +{{% notice warning %}} +Never modify directly files in the `languages` folder, this could lead to conflicts. {{% /notice %}} -{{% notice tip %}} -Please work on the `main` branch, and do your commits and pull request on this branch. -{{% /notice %}} +## How to -{{% notice note %}} -Until march 2023, contribution were made on the `develop` branch. This procedure is now deprecated. -{{% /notice %}} - -## Standard application strings - -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. +* 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 %}} + +## 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). diff --git a/support/documentation/content/contributing/translate/_index.fr.md b/support/documentation/content/contributing/translate/_index.fr.md index 2091411d..292d9649 100644 --- a/support/documentation/content/contributing/translate/_index.fr.md +++ b/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 %}} -Pour le moment, les traductions se font directement dans le dépôt git. -Plus tard en 2023, des outils de traduction en ligne seront mis en place -(probablement [Weblate](https://weblate.org)). -Le processus de traduction en sera plus simple. +{{% notice warning %}} +Ne modifiez jamais directement les fichiers dans le dossier `languages` du plugin, +vous risqueriez de créer des conflits. {{% /notice %}} -{{% notice tip %}} -Merci de travailler sur la branche `main`, et de faire vos _pull request_ sur cette branche. -{{% /notice %}} +## Comment faire -{{% notice note %}} -Jusqu'à mars 2023, il fallait contribuer sur la branche `develop`. Cette procédure est désormais obsolète. -{{% /notice %}} - -## Chaîne applicatives standard - -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. +* Créez-vous un compte: https://weblate.framasoft.org/accounts/register/ +* Validez votre email en cliquant sur le lien reçu +* 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/ +* 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. {{% 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).