Add json translation notes

retype.manifest

@@ -1,6 +1,6 @@
 {
   "version": "3.5.0",
-  "created": "2024-06-09T17:24:33Z",
+  "created": "2024-08-11T20.16.46Z",
   "files": [
     {
       "path": ".nojekyll"
@@ -91,6 +91,12 @@
     },
     {
       "path": "tags\\vehicle-detection\\index.html"
+    },
+    {
+      "path": "translation\\image.png"
+    },
+    {
+      "path": "translation\\json-translation\\index.html"
     }
   ]
 }

translation/JSON Translation.md

@@ -0,0 +1,119 @@
+---
+authors: 
+  - name: Tumppi066
+    link: https://github.com/Tumppi066
+    avatar: https://avatars.githubusercontent.com/u/83072683?v=4
+date: 2024-3-3
+icon: book
+tags: 
+  - tutorial
+---
+
+!!! Warning
+The translation backend and tokens are still not finalized. If you start translating now you might have to redo the work later on. 
+I DO NOT ACCEPT TRANSLATIONS DUE TO THIS YET!
+!!!
+### Introduction to V2.0 translation
+Unlike the previous versions, 2.0 has native translation support. This is done using several different json files.
+==+ [!badge variant="ghost" text="Do not edit this file!"] [!badge variant="dark" text="keys.json"] 
+This file contains all the translation keys, the app will validate translation files against the contents of this file.
+==+ [!badge variant="ghost" text="Do not edit this file!"] [!badge variant="dark" text="comments.json"] 
+This file is important! It contains comments for some of the keys. You should always check this file for any comments before translating.
+==+ [!badge variant="ghost" text="Do not edit this file!"] [!badge variant="dark" text="en.json"] 
+This file contains the base English translations. When translating use this as a reference point.
+==+
+
+### Language json file format
+==- `name`
+The name of the language in the language itself.
+==- `name_en`
+The name of the language in English.
+==- `iso_code`
+The ISO code of the language. Use the 2 letter code (`ISO 639-1 Code`) if your language has one, otherwise the 3 letter code (`ISO 639-2 Code`).
+https://www.loc.gov/standards/iso639-2/php/code_list.php
+!!! Note
+The iso_code variables **has to match** the file name of the translation file.
+!!!
+==- `_COMMENTS`
+Caps locked comments are comments only visible to editors that use the json files. Usually they are just used to explain the structure of the file.
+==- `_CoMMeNTS`
+Comments that are capitalized in any other way are shown to users of the translation UI. They might contain comments from translators to each other.
+==- `keys`
+This is how you actually translate. Just copy the key from keys.json and paste it, then add the translation.
+==-
+##### Example file:
+```json
+{
+  "name": "Suomi",
+  "name_en": "Finnish",
+  "iso_code": "fi",
+
+  "_GLOBALS": "Please leave a space here to seperate the different sections of the translations.",
+
+  "confirm": "Vahvista",
+  "cancel": "Peruuta",
+  "yes": "Kyllä",
+  "no": "Ei",
+  "continue": "Jatka",
+  "loading": "Ladataan...",
+  "success": "Onnistui",
+  "error": "Epäonnistui",
+  "done": "Valmis",
+  "set": "Asetettu",
+  "setting": "Asetetaan...",
+  "unknown": "Tuntematon",
+
+  "_BACKEND": "Please leave a space here to seperate the different sections of the translations.",
+
+  "main.errors_and_warnings": "Virheet ja varoitukset lokitiedostoissa:",
+  "main.errors": "Virheitä:",
+  "main.warnings": "Varoituksia:",
+  ...
+}
+```
+
+### Translation process
+==+ 1. Discord
+1. Go to the [ETS2LA Discord server](https://discord.gg/ETS2LA), then the [#roles](https://discord.com/channels/1120719484982939790/1133373947744878634) channel and press the button to get the translator role.
+2. Go to the [#translations](https://discord.com/channels/1120719484982939790/1272264777997226179) forum and find the post of the language you want to translate. If it doesn't exist, create a new post.
+3. If you are no the first person, then check with others on the current progress of the language (you can use `@here` to ping everyone that has commented on the post).
+==+ 2. Translation
+1. Copy the `en.json` file and rename it to your language's ISO code.
+2. Change the `name`, `name_en` and `iso_code` fields to match your language.
+3. Start translating the keys. **Make sure to check the comments.json file!**
+==+ 3. Testing
+1. If you didn't do so already, test the language in the app to make sure everything works.
+2. If you are not the only translator, I suggest asking for other people's opinions.
+!!! Note
+You can either change the language from the settings (once implemented) or the global.json file in `root/code/app/ETS2LA/global.json`.
+!!!
+==+ 4. Submitting
+1. Send the edited file in the discord forum of your own language. Then ping either *DylDev* or *Tumppi066* to update the translations with your file.
+!!! Note
+Remember that our timezones are different, so we might not be able to update the translations immediately.
+!!!
+##### Done!
+==+
+
+### Translation Guidelines
+!!! Note
+Anything written here is overwritten by the comments.json file if there is a conflict.
+!!!
+
+==+ General
+1. **Be consistent!** If you translate a word one way, keep it that way throughout the translation.
+2. **Work with others!** This is often a multi-person job, so make sure to communicate with the others to setup your own guidelines.
+   1. Regarding this if you want me to pin a message in the post, then just ask!
+3. **This is not a job!** If you don't have time to translate immediately, that's fine. Most of the time there are others and if you are the only translator, then don't worry about it!
+==+ Special characters
+1. **Preserve special characters!** If the English text has special characters (like `\n`, `\t`, `:` etc... or spaces at the start or end), make sure to keep them in the translation.
+2. **Do not add special characters!** If the English text doesn't have special characters, don't add them.
+==+ Variables
+We use variables in the translations to add dynamic content. They are written as `{0}`, `{1}`, `{2}` etc... and are replaced with the actual content when the translation is used. You can see what the variables mean in the comments.json file, this file also often includes examples of how the translation would look in english.
+
+**MAKE SURE TO KEEP ALL VARIABLES**
+==+
+
+### Not updating after translating!
+ ![From @onayB09 on discord!](image.png)
+If you get an error like this, then that means your local changes are preventing the app from updating. You should backup the file and then delete it. The app will then download the latest version of the file.