Localization refactoring:

* the front-end now use global constants, based on the translation key
* build-client.js use the ESBuild "define" directive to replace these
  globals at compile time, by the english value
* build:client must now be called after build:languages
* moving the loadLoc and loc backend functions in a separate lib

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

@@ -45,14 +45,38 @@ If you are working on new features, and need new strings, you can create them di
 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.
+Choose an explicit key in english, lower case.
 
-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.
+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).
 
-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.
+### Use translations in front-end code
 
-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).
+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. 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')`'.

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

@@ -50,18 +50,39 @@ 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.
+Choisissez une clé en anglais, suffisamment explicite, et en minuscule.
 
 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).
+
+### Utiliser un segment dans le code front-end
+
+Avant d'utiliser une chaîne en front-end, il faut déclarer une nouvelle constante dans `client/@types/global.d.ts`.
+La constante doit :
+
+* commencer par le préfixe "LOC_"
+* utiliser la clé de la chaîne, en majuscule
+* vous ne devez déclarer que son type, pas sa valeur
+
+Par exemple, pour utiliser "use_chat", vous devez déclarer :
+e, to use "use_chat", you have to declare:
+
+```typescript
+declare const LOC_USE_CHAT: string
+```
+
+Le script `build-client.js` va lire ce fichier `client/@types/global.d.ts`, chercher pour de telles constantes, et charger leurs valeurs depuis le fichier de langue.
+
+Vous pouvez maintenant utiliser `peertubeHelpers.translate(LOC_USE_CHAT)` dans votre code.
+
+### Utiliser un segment dans le code back-end
+
+En théorie, les seules parties du code qui ont besoin de traductions sont les déclarations de paramètres.
+Ici on a besoin de récupérer les chaînes anglaises à partir des clés de traduction.
+
+Note: vous ne devriez jamais avoir besoin d'autres langues que l'anglais pour le code backend.
+Les traductions doivent se faire coté front-end.
+
+Il y a un module `lib/loc.ts` qui fourni une function `loc()`.
+Passez juste la clé pour récupérer la phrase anglaise: `loc('diagnostic')`.