docs: update README language list + refresh CONTRIBUTING i18n guide for locale loaders

Author: error311

CONTRIBUTING.md

@@ -25,11 +25,11 @@ Thank you for your interest in contributing to FileRise! We appreciate your help
    cd FileRise
    ```
 
-3. **Set Up a Local Environment**
-FileRise runs on a standard LAMP stack. Ensure you have PHP, Apache, and the necessary dependencies installed.
+3. **Set Up a Local Environment**  
+   FileRise runs on a standard LAMP stack. Ensure you have PHP, Apache, and the necessary dependencies installed.
 
-4. **Configuration**
-Copy any example configuration files (if provided) and adjust them as needed for your local setup.
+4. **Configuration**  
+   Copy any example configuration files (if provided) and adjust them as needed for your local setup.
 
 ## Reporting Bugs
 
@@ -90,153 +90,84 @@ If you have any questions, ideas, or need support, please open an issue or join
 
 ## Adding New Language Translations
 
-FileRise supports internationalization (i18n) and localization via a central translation file (`i18n.js`). If you would like to contribute a new language translation, please follow these steps:
-
-1. **Update `i18n.js`:**  
-   Open the `i18n.js` file located in the `js` directory. Within the `translations` object, add a new property using the appropriate [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) as the key. Copy the structure from an existing language block and translate each key.
-
-   **Example (for German):**
-
-   ```js
-   de: {
-     "please_log_in_to_continue": "Bitte melden Sie sich an, um fortzufahren.",
-     "no_files_selected": "Keine Dateien ausgewählt.",
-     "confirm_delete_files": "Sind Sie sicher, dass Sie {count} ausgewählte Datei(en) löschen möchten?",
-     "element_not_found": "Element mit der ID \"{id}\" wurde nicht gefunden.",
-     "search_placeholder": "Suche nach Dateien oder Tags...",
-     "file_name": "Dateiname",
-     "date_modified": "Änderungsdatum",
-     "upload_date": "Hochladedatum",
-     "file_size": "Dateigröße",
-     "uploader": "Hochgeladen von",
-     "enter_totp_code": "Geben Sie den TOTP-Code ein",
-     "use_recovery_code_instead": "Verwenden Sie stattdessen den Wiederherstellungscode",
-     "enter_recovery_code": "Geben Sie den Wiederherstellungscode ein",
-     "editing": "Bearbeitung",
-     "decrease_font": "A-",
-     "increase_font": "A+",
-     "save": "Speichern",
-     "close": "Schließen",
-     "no_files_found": "Keine Dateien gefunden.",
-     "switch_to_table_view": "Zur Tabellenansicht wechseln",
-     "switch_to_gallery_view": "Zur Galerieansicht wechseln",
-     "share_file": "Datei teilen",
-     "set_expiration": "Ablauf festlegen:",
-     "password_optional": "Passwort (optional):",
-     "generate_share_link": "Freigabelink generieren",
-     "shareable_link": "Freigabelink:",
-     "copy_link": "Link kopieren",
-     "tag_file": "Datei taggen",
-     "tag_name": "Tagname:",
-     "tag_color": "Tagfarbe:",
-     "save_tag": "Tag speichern",
-     "files_in": "Dateien in",
-     "light_mode": "Heller Modus",
-     "dark_mode": "Dunkler Modus",
-     "upload_instruction": "Ziehen Sie Dateien/Ordner hierher oder klicken Sie auf 'Dateien auswählen'",
-     "no_files_selected_default": "Keine Dateien ausgewählt",
-     "choose_files": "Dateien auswählen",
-     "delete_selected": "Ausgewählte löschen",
-     "copy_selected": "Ausgewählte kopieren",
-     "move_selected": "Ausgewählte verschieben",
-     "tag_selected": "Ausgewählte taggen",
-     "download_zip": "Zip herunterladen",
-     "extract_zip": "Zip entpacken",
-     "preview": "Vorschau",
-     "edit": "Bearbeiten",
-     "rename": "Umbenennen",
-     "trash_empty": "Papierkorb ist leer.",
-     "no_trash_selected": "Keine Elemente im Papierkorb für die Wiederherstellung ausgewählt.",
-  
-     // Additional keys for HTML translations:
-     "title": "FileRise",
-     "header_title": "FileRise",
-     "logout": "Abmelden",
-     "change_password": "Passwort ändern",
-     "restore_text": "Wiederherstellen oder",
-     "delete_text": "Papierkorbeinträge löschen",
-     "restore_selected": "Ausgewählte wiederherstellen",
-     "restore_all": "Alle wiederherstellen",
-     "delete_selected_trash": "Ausgewählte löschen",
-     "delete_all": "Alle löschen",
-     "upload_header": "Dateien/Ordner hochladen",
-  
-     // Folder Management keys:
-     "folder_navigation": "Ordnernavigation & Verwaltung",
-     "create_folder": "Ordner erstellen",
-     "create_folder_title": "Ordner erstellen",
-     "enter_folder_name": "Geben Sie den Ordnernamen ein",
-     "cancel": "Abbrechen",
-     "create": "Erstellen",
-     "rename_folder": "Ordner umbenennen",
-     "rename_folder_title": "Ordner umbenennen",
-     "rename_folder_placeholder": "Neuen Ordnernamen eingeben",
-     "delete_folder": "Ordner löschen",
-     "delete_folder_title": "Ordner löschen",
-     "delete_folder_message": "Sind Sie sicher, dass Sie diesen Ordner löschen möchten?",
-     "folder_help": "Ordnerhilfe",
-     "folder_help_item_1": "Klicken Sie auf einen Ordner, um dessen Dateien anzuzeigen.",
-     "folder_help_item_2": "Verwenden Sie [-] um zu minimieren und [+] um zu erweitern.",
-     "folder_help_item_3": "Klicken Sie auf \"Ordner erstellen\", um einen Unterordner hinzuzufügen.",
-     "folder_help_item_4": "Um einen Ordner umzubenennen oder zu löschen, wählen Sie ihn und klicken Sie auf die entsprechende Schaltfläche.",
-  
-     // File List keys:
-     "file_list_title": "Dateien in (Root)",
-     "delete_files": "Dateien löschen",
-     "delete_selected_files_title": "Ausgewählte Dateien löschen",
-     "delete_files_message": "Sind Sie sicher, dass Sie die ausgewählten Dateien löschen möchten?",
-     "copy_files": "Dateien kopieren",
-     "copy_files_title": "Ausgewählte Dateien kopieren",
-     "copy_files_message": "Wählen Sie einen Zielordner, um die ausgewählten Dateien zu kopieren:",
-     "move_files": "Dateien verschieben",
-     "move_files_title": "Ausgewählte Dateien verschieben",
-     "move_files_message": "Wählen Sie einen Zielordner, um die ausgewählten Dateien zu verschieben:",
-     "move": "Verschieben",
-     "extract_zip_button": "Zip entpacken",
-     "download_zip_title": "Ausgewählte Dateien als Zip herunterladen",
-     "download_zip_prompt": "Geben Sie einen Namen für die Zip-Datei ein:",
-     "zip_placeholder": "dateien.zip",
-  
-     // Login Form keys:
-     "login": "Anmelden",
-     "remember_me": "Angemeldet bleiben",
-     "login_oidc": "Mit OIDC anmelden",
-     "basic_http_login": "HTTP-Basisauthentifizierung verwenden",
-  
-     // Change Password keys:
-     "change_password_title": "Passwort ändern",
-     "old_password": "Altes Passwort",
-     "new_password": "Neues Passwort",
-     "confirm_new_password": "Neues Passwort bestätigen",
-  
-     // Add User keys:
-     "create_new_user_title": "Neuen Benutzer erstellen",
-     "username": "Benutzername:",
-     "password": "Passwort:",
-     "grant_admin": "Admin-Rechte vergeben",
-     "save_user": "Benutzer speichern",
-  
-     // Remove User keys:
-     "remove_user_title": "Benutzer entfernen",
-     "select_user_remove": "Wählen Sie einen Benutzer zum Entfernen:",
-     "delete_user": "Benutzer löschen",
-  
-     // Rename File keys:
-     "rename_file_title": "Datei umbenennen",
-     "rename_file_placeholder": "Neuen Dateinamen eingeben",
-  
-     // Custom Confirm Modal keys:
-     "yes": "Ja",
-     "no": "Nein",
-     "delete": "Löschen",
-     "download": "Herunterladen",
-     "upload": "Hochladen",
-     "copy": "Kopieren",
-     "extract": "Entpacken",
-  
-     // Dark Mode Toggle
-     "dark_mode_toggle": "Dunkler Modus"
-   }
+FileRise supports internationalization (i18n). English (`en`) lives in `public/js/i18n.js`, and additional languages are loaded from separate locale files under:
+
+- `FileRise/public/js/i18n/locales/`
+
+When a translation key is missing in a locale, FileRise automatically falls back to English.
+
+### Supported languages (current)
+
+See `localeLoaders` in:
+
+- `FileRise/public/js/i18n.js`
+
+(Example codes include: `de`, `es`, `fr`, `pl`, `ru`, `ja`, `zh-CN`.)
+
+### How language selection works
+
+- Users can choose a language in the UI (stored in `localStorage`).
+- Admins can optionally set a **Default language** used when a user has not chosen one yet.
+- Client Portals include a language selector and use the same translation system.
+
+### Add a new language (step-by-step)
+
+1) **Pick a language code**
+Use ISO 639-1 codes when possible (e.g., `it`, `pt`, `nl`).  
+For region-specific variants, use a BCP-47 tag (e.g., `pt-BR`, `zh-CN`).
+
+2) **Create the locale file**
+Add a new file:
+
+- `FileRise/public/js/i18n/locales/<code>.js`
+
+It must export a default object of `key: "translation"` pairs.
+
+Example (`it.js`):
+```js
+export default {
+  "please_log_in_to_continue": "Accedi per continuare.",
+  "no_files_selected": "Nessun file selezionato.",
+  "download_zip": "Scarica archivio",
+};
+```
+
+3) **Register the locale loader**
+In `FileRise/public/js/i18n.js`, add your language to `localeLoaders`:
+
+```js
+const localeLoaders = {
+  // ...
+  it: () => import(new URL('./i18n/locales/it.js?v={{APP_QVER}}', import.meta.url)),
+};
+```
+
+4) **Keep placeholders intact**
+Some strings contain placeholders like:
+- `{count}`, `{id}`, `{name}`, `{folder}`, `{error}`
+
+Do **not** remove or rename placeholders. Translate only the surrounding text.
+
+5) **Avoid HTML in translations**
+Translations should be plain text. Do not embed raw HTML tags in locale values.
+
+6) **Test the language**
+- Switch the language in the main UI.
+- Also test Portals:
+  - `/portal/<slug>`
+  - `/portal-login.html?...`
+- Click through a few key flows to confirm strings render correctly:
+  - Login + TOTP prompts
+  - Uploads (including error/success toasts)
+  - File actions (copy/move/delete/download/archive)
+  - Share modals
+  - Admin panel (partial coverage is OK; missing keys fall back to English)
+
+### Improving existing translations / missing keys
+
+If you notice untranslated text:
+- Prefer adding a new i18n key to English in `public/js/i18n.js` and then translating it in the locale files.
+- If you’re not sure where a string is used, search the codebase for the key or the English phrase.
 
 ---
 

README.md

@@ -33,7 +33,7 @@ Drag & drop uploads, OnlyOffice integration, and **optional folder-level encrypt
 - 📚 **API + live docs** – OpenAPI spec (`openapi.json`) plus an embedded Redoc viewer (`api.html`) for exploring endpoints.
 - 📊 **Storage / disk usage summary** – CLI scanner with snapshots, total usage, and per-volume breakdowns surfaced in the admin panel.
 - 🎨 **Polished, responsive UI** – Dark/light mode, mobile-friendly layout, in-browser previews, and a built-in code editor powered by CodeMirror.
-- 🌐 **Internationalization** – English, Spanish, French, German, and Simplified Chinese included; community translations welcome.
+- 🌐 **Internationalization** – English, Spanish, French, German, Polish, Russian, Japanese and Simplified Chinese included; community translations welcome.
 - 🔑 **Login + SSO** – Local users, TOTP 2FA, and OIDC (Auth0 / Authentik / Keycloak / etc.) with optional auto-provisioning, IdP-driven admin role assignment, and Pro user-group mapping.
 - 🛡️ **ClamAV virus scanning (Core) + Pro virus log** – Optional ClamAV upload scanning, with a Pro virus detection log in the admin panel and CSV export.
 - 🌐 **Reverse proxy & subpath aware** – Designed to run cleanly behind Nginx, Traefik, Caddy, or Apache: