imap-backup 16.5.0 → 16.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d4ce42bf0d3de92eaa3355305f422bdccaf627e4d9cc31cb14c128417d2b87d
-  data.tar.gz: 513fc795468450786093972b7ad3fc5ec024a0ed86f11728443342dd41b04980
+  metadata.gz: 325c46cce0eff42c96d4c44e686b32f0d52352cdfa038c17a132069b71bdf11e
+  data.tar.gz: 349426301b37fa38db3da6c2d71a3979892345828b88ffa2b52752a559f6a95b
 SHA512:
-  metadata.gz: 460cc300cb717a129a440a3d7c542475ed6122f6dfc55e1b643c707e6575450c35d5c331b328596763b87a5426a2ce5f15a27830d739d772dfd14ae1f7b75a8b
-  data.tar.gz: 20917771c877b133363f7d192df3293a9eb4fd234e23aee7f9018365e9caed492cc03c283526a069260f5091333a50f0b9c011a59de96d6027cb510e8cf5d6dc
+  metadata.gz: 6c4735412c68747d5365048e7748cc849bb1302a2da6e4af60354bf2a44c3c4dab5f14cf9ea7111cd7c6f416faea8ad429657a551755167662998e20ff7aae3a
+  data.tar.gz: 213bc6df849b8e7d72ded14920695e1a158d8657ac0d3bcd6632068f0c76258d2b5d0f37a5073867cf1f549249b1a2df651a0327ce803051311ed33fe5e757a0

data/docs/TODO.md

@@ -14,3 +14,22 @@ Add internationalization support to make imap-backup accessible to non-English-s
 - Prioritize translating the menu-driven setup interface (`lib/imap/backup/setup.rb` and related files)
 - Extract all user-facing strings into translation files with locale "en"
 - Add Italian translations
+
+# Add Localized Help to All Setup Screens
+
+Status: [x]
+
+## Description
+
+Currently, only the Download Strategy Chooser screen has localized help functionality (via the `show_help` method). This TODO involves adding similar localized help to all other setup screens in the menu-driven interface to provide users with context-sensitive assistance in their preferred language.
+
+## Technical Specifics
+
+- The Download Strategy Chooser at [lib/imap/backup/setup/global_options/download_strategy_chooser.rb](lib/imap/backup/setup/global_options/download_strategy_chooser.rb#L52-L56) already implements localized help as a reference implementation
+- Screens that need localized help added:
+  - Main menu ([lib/imap/backup/setup.rb](lib/imap/backup/setup.rb))
+  - Account setup menu ([lib/imap/backup/setup/account.rb](lib/imap/backup/setup/account.rb))
+  - Global options menu ([lib/imap/backup/setup/global_options.rb](lib/imap/backup/setup/global_options.rb))
+  - Other setup screens (folder chooser, backup path, etc.)
+- Add translation keys for help text to locale files (`lib/imap/backup/locales/en.yml` and `lib/imap/backup/locales/it.yml`)
+- Follow the pattern: menu choice for "help" that displays localized help text and waits for key press

data/docs/i18n.md

@@ -41,9 +41,9 @@ Translation files use a hierarchical structure with nested keys. Here's an examp
 ---
 en:
   setup:
+    choose_action: "Choose an action"
     main_menu:
       title: "Main Menu"
-      choose_action: "Choose an action"
       add_account: "add account"
 ```
 
@@ -87,9 +87,9 @@ To add support for a new language:
    ---
    fr:
      setup:
+       choose_action: "Choisissez une action"
        main_menu:
          title: "Menu Principal"
-         choose_action: "Choisissez une action"
          # ... continue translating all keys
    ```
 

data/lib/imap/backup/locales/de.yml

@@ -0,0 +1,218 @@
+---
+de:
+  setup:
+    return_to_main_menu: "(q) Zurück zum Hauptmenü"
+    press_key: "Drück eine Taste "
+    choose_action: "Wählen eine Aktion aus"
+    main_menu:
+      title: "Hauptmenü"
+      add_account: "Konto hinzufügen"
+      modify_global_options: "Globale Einstellungen ändern"
+      help: "Hilfe"
+      help_text: |
+        imap-backup hilft dir dabei, deine E-Mail-Konten zu sichern und wiederherzustellen.
+
+        Aus diesem Menü kannst du folgende Aktionen durchführen:
+        - Neue E-Mail-Konten für die Sicherung hinzufügen
+        - Bestehende Konto-Einstellungen bearbeiten
+        - Globale Einstellungen ändern
+      save_and_exit: "Speichern und Beenden"
+      exit_without_saving: "Ohne Speichern Beenden"
+      quit: "(q) Beenden"
+    account:
+      title: "Konto"
+      email: "E-Mail-Adresse"
+      password: "Passwort"
+      password_unset: "(Nicht festgelegt)"
+      server: "Server"
+      connection_options: "Verbindungsoptionen"
+      mode: "Modus"
+      mirror_emails: "E-Mails spiegeln"
+      keep_all_emails: "Alle E-Mails behalten"
+      path: "Sicherungspfad"
+      exclude: "Ausschließen"
+      include: "Einschließen"
+      all_folders: "(Alle Ordner)"
+      no_folders_warning: "(Alle Ordner) <- Du hast dich dazu entschieden, keine Ordner zu sichern!"
+      multi_fetch: "Multi-Abruf"
+      reset_seen_flags_message: "Änderungen an „UNREAD“-Kennzeichnungen werden während des Downloads zurückgesetzt"
+      status: "Status"
+      connection_configuration: "Verbindungskonfiguration"
+      modify_email: "E-Mail-Adresse ändern"
+      modify_password: "Passwort ändern"
+      modify_server: "Server ändern"
+      server_prompt: "Server: "
+      modify_connection_options: "Verbindungsoptionen ändern"
+      connection_options_prompt: "Verbindungsoptionen (als JSON): "
+      malformed_json: "Fehlerhaftes JSON, bitte versuche es erneut"
+      test_connection: "Verbindung testen"
+      backup_configuration: "Sicherungskonfiguration"
+      toggle_mirror_mode: "Modus umschalten („Behalten“/„Spiegeln“)"
+      modify_backup_path: "Sicherungspfad ändern"
+      toggle_folder_blacklist: "Ordner-Einschließmodus umschalten (Whitelist/Blacklist)"
+      choose_folders: "Ordner zu %{action} auswählen"
+      exclude_from_backups: "Aus Sicherungen ausschließen"
+      include_in_backups: "In Sicherungen einschließen"
+      modify_multi_fetch_size: "Größe des Multi-Abrufs ändern (Anzahl der E-Mails, die gleichzeitig abgerufen werden sollen)"
+      size_prompt: "Größe: "
+      dont_fix_unread_flags: "Änderung an „UNREAD“-Kennzeichnungen während des Downloads nicht korrigieren"
+      fix_unread_flags: "Änderungen an „UNREAD“-Kennzeichnungen während des Downloads korrigieren"
+      change_status: "Status ändern (%{current} -> %{next})"
+      danger_area: "Gefahrenbereich"
+      delete: "Löschen"
+      delete_confirm: "Bist du sicher? (y/n) "
+      other_actions: "Andere Aktionen"
+      help: "Hilfe"
+      help_text: |
+        Dieses Menü ermöglicht es dir, Verbindungs- und Sicherungseinstellungen für ein einzelnes E-Mail-Konto zu konfigurieren.
+
+        Verbindungseinstellungen:
+        - `E-Mail-Adresse` und `Passwort` - Die Zugangsdaten für das Konto
+        - `Server` - Der Server, mit dem eine Verbindung für dieses Konto hergestellt wird.
+            Du musst dies nicht einstellen, wenn du einen der folgenden Anbieter verwendest: GMail, Apple Mail, FastMail, PurelyMail.
+            Andernfalls musst du hier den IMAP-Server deines E-Mail-Anbieters angeben.
+        - `Verbindungsoptionen` - (Erweiterte Einstellung) Damit kannst du zusätzliche Optionen für die IMAP-Verbindung angeben.
+            Dies sollte ein JSON-Objekt sein mit Schlüsseln, die den in der Ruby-Standardbibliothek `net/imap` beschriebenen Optionen entsprechen:
+            https://ruby-doc.org/stdlib-3.2/libdoc/net/imap/rdoc/Net/IMAP.html#initialize-instance_method
+            Wenn dein Server zum Beispiel SSL unterstützt aber ein ungültiges Zertifikat hat, kannst du diese Einstellung verwenden: `{"ssl": {"verify_mode": "none"}}`.
+
+        Du kannst überprüfen, ob deine Verbindungseinstellungen korrekt sind, indem du die Option „Verbindung testen“ auswählst.
+
+        Sicherungseinstellungen:
+        - `Modus` - „Alle E-Mails behalten“ bedeutet, dass E-Mails, die vom Server gelöscht wurden, weiterhin in der Sicherung behalten werden,
+            während „E-Mails spiegeln“ bedeutet, dass E-Mails, die vom Server gelöscht wurden, auch aus der Sicherung gelöscht werden.
+        - `Sicherungspfad` - Das Verzeichnis auf deinem lokalen Rechner, in dem die Sicherung für dieses Konto gespeichert wird.
+        - `Ordner-Einbindungsmodus` - Diese Einstellung bestimmt, ob du Ordner zum *Einschließen* in die Sicherung auswählst (Whitelist-Modus)
+            oder Ordner zum *Ausschließen* aus der Sicherung auswählst (Blacklist-Modus).
+            Im Whitelist-Modus startest du ohne Ordner und wählst aus, welche Ordner zur Sicherung hinzugefügt werden sollen.
+            Im Blacklist-Modus startest du mit allen Ordnern in der Sicherung und wählst aus, welche Ordner ausgeschlossen werden sollen.
+        - `Multi-Abruf-Größe` - Die Anzahl der E-Mails, die gleichzeitig vom Server abgerufen werden, wenn die Sicherung läuft.
+            Eine Erhöhung dieser Größe kann die Sicherung beschleunigen, aber auch den Speicherverbrauch erhöhen.
+        - `Änderungen an „UNREAD“-Kennzeichnungen korrigieren` - Legt fest, ob Änderungen an „UNREAD“-Kennzeichnungen während des Downloads zurückgesetzt werden sollen.
+            Diese Kennzeichnung ist nützlich, wenn der E-Mail-Anbieter (z.B. Apple Mail) E-Mails als gelesen markiert, wenn sie z.B. durch imap-backup heruntergeladen werden.
+        - `Status`- Standardmäßig ist ein Konto „aktiv“ und wird gesichert, wenn du den Sicherungsbefehl ausführst.
+            Du kannst den Status auf „Archiviert“ stellen, wenn du die Sicherungen nicht mehr ausführen möchtest, aber sie in Zukunft mit dem `copy`-Befehl auf einen neuen Server migrieren möchtest. Andernfalls kannst du ihn auf „Offline“ stellen, wenn du nur die Sicherung des Kontos auf dem Datenträger behalten möchtest.
+    global_options:
+      title: "Globale Optionen"
+      description: "Diese Einstellungen betreffen alle Konten."
+      change_download_strategy: "Download-Strategie ändern (Ausgewählt: „%{current}“)"
+      help: "Hilfe"
+      help_text: |
+        Dieses Menü ermöglicht es dir, Einstellungen zu konfigurieren, die alle Konten betreffen.
+
+        Verfügbaren globale Optionen:
+        - `Download-Strategie` - Diese Einstellung bestimmt, wie oft Daten während der Sicherung auf den Datenträger geschrieben werden.
+            Die Standardeinstellung („Metadaten verzögert schreiben“) ist schneller und schonender für den Datenträger,
+            während „Direkt auf den Datenträger schreiben“ weniger Arbeitsspeicher verwendet und für Geräte mit begrenztem Arbeitsspeicher geeignet ist.
+            Wähle die Option für weitere Details zu den Unterschieden zwischen diesen Strategien.
+      download_strategy_chooser:
+        title: "Wähle eine Download-Strategie aus"
+        current_marker: " <- Ausgewählt"
+        help: "Hilfe"
+        help_text: |
+          Die Einstellung ändert, wie oft Daten während der Sicherung auf den Datenträger geschrieben werden.
+
+          imap-backup verwendet zwei Dateien pro Ordner, eine .mbox-Datei mit den eigentlichen
+          Nachrichten und eine .imap-Datei mit Metadaten wie Nachrichtenlängen und deren
+          Offsets innerhalb der .mbox-Datei.
+
+          # „Direkt auf den Datenträger schreiben“
+
+          Mit dieser Einstellung werden jede Nachricht und ihre Metadaten
+          auf den Datenträger geschrieben, sobald sie heruntergeladen werden.
+
+          Diese Option verwendet am wenigsten Arbeitsspeicher und ist daher für
+          Sicherungen auf Geräten mit begrenztem Arbeitsspeicher, wie Raspberry Pis, geeignet.
+
+          # „Metadaten verzögert schreiben“
+
+          Dies ist die Standardeinstellung.
+
+          Hier werden Nachrichten (die potenziell sehr groß sind) an die
+          .mbox-Datei angehängt, sobald sie empfangen werden, aber die
+          Metadaten werden erst geschrieben, wenn alle Nachrichten des
+          Ordners heruntergeladen wurden.
+
+          Diese Option verwendet etwas mehr Arbeitsspeicher als die vorherige
+          Einstellung, ist aber **viel** schneller für große Ordner (potenziell
+          >30 mal für Ordner mit >100k Nachrichten) und ist schonender für den Datenträger.
+
+          # Andere Leistungseinstellungen
+
+          Eine weitere Einstellung, die die Leistung der Sicherung beeinflusst,
+          ist die `Multi-Abruf-Größe` Kontoeinstellung.
+    asker:
+      email_prompt: "E-Mail-Adresse: "
+      email_validation_error: "Gib eine gültige E-Mail-Adresse ein "
+      password_prompt: "Passwort: "
+      password_confirmation_prompt: "Passwort wiederholen: "
+      password_mismatch: "Das Passwort und die Wiederholung stimmen nicht überein.\nWeiter? (y/n) "
+    folder_chooser:
+      title: "Ordner hinzufügen/entfernen"
+      select_folder: "Wähle eine Ordner aus (Aktivieren/Deaktivieren)"
+      help: "Hilfe"
+      help_text: |
+        Verwende dieses Menü, um auszuwählen, welche Ordner gesichert werden sollen.
+
+        Klick auf einen Ordner, um seinen Sicherungsstatus umzuschalten:
+        - Ordner mit einem „+“ markiert werden gesichert
+        - Ordner mit einem „-“ markiert werden nicht gesichert
+
+        Wenn du keine Ordner auswählst, werden alle Ordner gesichert.
+      return_to_account_menu: "(q) Zum Kontomenü zurückkehren"
+      unable_to_get_folder_list: "Ordnerliste konnte nicht abgerufen werden"
+      folders_removed: "Die folgenden Ordner wurden entfernt: %{folders}"
+      connection_failed: "Verbindung fehlgeschlagen"
+    backup_path:
+      prompt: "Sicherungsverzeichnis: "
+      validation_error: "Wähle ein anderes Verzeichnis aus "
+      path_in_use: "Der Pfad „%{path}“ wird bereits für die Sicherung des Kontos „%{username}“ verwendet"
+  cli:
+    version: "imap-backup %{version}"
+    stats:
+      folder: "Ordner"
+      remote: "Entfernt"
+      both: "Beide"
+      local: "Lokal"
+    local:
+      check:
+        account: "Konto: %{account}"
+      folder_not_found: "Ordner „%{folder}“ nicht gefunden"
+    remote:
+      namespaces:
+        name: "Name"
+        prefix: "Prefix"
+        delimiter: "Trennzeichen"
+        not_defined: "(Nicht festgelegt)"
+    restore:
+      missing_email_parameter: "Fehlender EMAIL-Parameter"
+    transfer:
+      same_account_error: "Quell- und Zielkonto dürfen nicht identisch sein!"
+      destination_not_found: "Das Konto „%{email}“ existiert nicht"
+      source_not_found: "Das Konto „%{email}“ existiert nicht"
+      source_not_available: "Das Konto „%{email}“ ist für die Migration nicht verfügbar (Status: %{status})"
+      destination_not_available: "Das Konto „%{email}“ ist für die Migration nicht verfügbar (Status: %{status})"
+      incompatible_destination_delimiter: "--automatic-namespaces ist inkompatibel mit --destination-delimiter"
+      incompatible_destination_prefix: "--automatic-namespaces ist inkompatibel mit --destination-prefix"
+      incompatible_source_delimiter: "--automatic-namespaces ist inkompatibel mit --source-delimiter"
+      incompatible_source_prefix: "--automatic-namespaces ist inkompatibel mit --source-prefix"
+    helpers:
+      config_mutual_exclusivity: "--config und --erb-configuration Optionen können nicht zusammen verwendet werden"
+      config_not_found: "Konfigurationsdatei „%{path}“ nicht gefunden"
+      account_not_configured: "%{email} ist kein konfiguriertes Konto"
+      erb_config_not_found: "Die ERB-Konfigurationsdatei „%{path}“ wurde nicht gefunden"
+      erb_syntax_error: "Die ERB-Vorlage hat einen Syntaxfehler: %{message}"
+      erb_processing_error: "Fehler beim Verarbeiten der ERB-Vorlage: %{message}"
+      erb_invalid_json: "Die ERB-Vorlage hat ein ungültiges JSON erzeugt: %{message}"
+    utils:
+      thunderbird_profile_not_found: "Thunderbird-Profil „%{profile}“ nicht gefunden"
+      default_thunderbird_profile_not_found: "Standard Thunderbird-Profil nicht gefunden"
+      no_serialized_folders: "Für das Konto „%{email}“ wurden keine serialisierten Ordner gefunden"
+  configuration:
+    download_strategy:
+      direct:
+        short: "Direkt auf den Datenträger schreiben"
+        long: "Auf Datenträger schreiben, sobald Nachrichten heruntergeladen werden"
+      delay_metadata:
+        short: "Verzögertes Schreiben der Metadaten"
+        long: "Metadaten erst schreiben, wenn alle Nachrichten heruntergeladen wurden"

data/lib/imap/backup/locales/en.yml

@@ -1,62 +1,112 @@
 ---
 en:
   setup:
+    return_to_main_menu: "(q) return to main menu"
+    press_key: "Press a key "
+    choose_action: "Choose an action"
     main_menu:
       title: "Main Menu"
-      choose_action: "Choose an action"
       add_account: "add account"
       modify_global_options: "modify global options"
+      help: "help"
+      help_text: |
+        imap-backup helps you backup and restore your email accounts.
+
+        From this main menu, you can:
+        - Add new email accounts to backup
+        - Edit existing account settings
+        - Modify global options
       save_and_exit: "save and exit"
       exit_without_saving: "exit without saving changes"
       quit: "(q) quit"
     account:
       title: "Account"
-      choose_action: "Choose an action"
+      email: "email"
+      password: "password"
+      password_unset: "(unset)"
+      server: "server"
+      connection_options: "connection options"
+      mode: "mode"
+      mirror_emails: "mirror emails"
+      keep_all_emails: "keep all emails"
+      path: "backup path"
+      exclude: "exclude"
+      include: "include"
+      all_folders: "(all folders)"
+      no_folders_warning: "(all folders) <- you have opted to not backup any folders!"
+      multi_fetch: "multi-fetch"
+      reset_seen_flags_message: "changes to 'UNSEEN' flags will be reset during download"
+      status: "status"
+      connection_configuration: "Connection Configuration"
       modify_email: "modify email"
       modify_password: "modify password"
+      modify_server: "modify server"
+      server_prompt: "server: "
+      modify_connection_options: "modify connection options"
+      connection_options_prompt: "connection options (as JSON): "
+      malformed_json: "Malformed JSON, please try again"
+      test_connection: "test connection"
+      backup_configuration: "Backup Configuration"
+      toggle_mirror_mode: "toggle mode ('keep'/'mirror')"
       modify_backup_path: "modify backup path"
       toggle_folder_blacklist: "toggle folder inclusion mode (whitelist/blacklist)"
       choose_folders: "choose folders to %{action}"
       exclude_from_backups: "exclude from backups"
       include_in_backups: "include in backups"
-      toggle_mirror_mode: "toggle mode ('keep'/'mirror')"
       modify_multi_fetch_size: "modify multi-fetch size (number of emails to fetch at a time)"
       size_prompt: "size: "
-      modify_server: "modify server"
-      server_prompt: "server: "
-      modify_connection_options: "modify connection options"
-      connection_options_prompt: "connection options (as JSON): "
-      malformed_json: "Malformed JSON, please try again"
-      press_key: "Press a key "
       dont_fix_unread_flags: "don't fix changes to 'UNSEEN' flags during download"
       fix_unread_flags: "fix changes to 'UNSEEN' flags during download"
       change_status: "change status (%{current} -> %{next})"
-      test_connection: "test connection"
+      danger_area: "Danger Area"
       delete: "delete"
       delete_confirm: "Are you sure? (y/n) "
-      return_to_main_menu: "(q) return to main menu"
-      email: "email"
-      password: "password"
-      unset: "(unset)"
-      path: "path"
-      exclude: "exclude"
-      include: "include"
-      all_folders: "(all folders)"
-      no_folders_warning: "(all folders) <- you have opted to not backup any folders!"
-      mirror_emails: "mirror emails"
-      keep_all_emails: "keep all emails"
-      mode: "mode"
-      multi_fetch: "multi-fetch"
-      server: "server"
-      connection_options: "connection options"
-      reset_seen_flags_message: "changes to 'UNSEEN' flags will be reset during download"
-      status: "status"
+      other_actions: "Other Actions"
+      help: "help"
+      help_text: |
+        This screen allows you to configure connection and backup settings for a single email account.
+
+        Connection settings:
+        - `email` and `password` - The credentials for the account
+        - `server` - The server to connect to for this account. You won't need to set this if you use
+            one of the following: GMail, Apple Mail, FastMail, PurelyMail.
+            Otherwise, you'll need to set this to your email provider's IMAP server.
+        - `connection_options` - (Advanced setting) This allows you to specify additional options for the IMAP connection.
+            This should be a JSON object with keys corresponding to the options described in the `net/imap` Ruby standard library documentation:
+            https://ruby-doc.org/stdlib-3.2/libdoc/net/imap/rdoc/Net/IMAP.html#initialize-instance_method
+            For example, if your server uses SSL but has an invalid certificate, you could set this to `{"ssl": {"verify_mode": "none"}}`.
+
+        You can test whether your connection settings are correct by selecting the "test connection" option.
+
+        Backup settings:
+        - `mode` - "keep all emails" means that emails deleted from the server will still be kept in the backup,
+            while "mirror emails" means that emails deleted from the server will also be deleted from the backup.
+        - `backup path` - The directory on your local machine where the backup for this account will be stored.
+        - `folder inclusion mode` - This setting determines whether you choose folders to *include* in the backup (whitelist mode)
+            or *exclude* from the backup (blacklist mode).
+            In whitelist mode, you start with an empty set of folders and choose which folders to add to the backup.
+            In blacklist mode, you start with all folders included in the backup and choose which folders to exclude.
+        - `multi-fetch size` - The number of emails to fetch at a time when backing up.
+            Increasing this can speed up backups, but also increases memory usage.
+        - `fix changes to 'UNSEEN' flags` - Whether to reset changes to 'UNSEEN' flags during download.
+            This flag is useful when the email provider (e.g. Apple Mail) marks emails as read when they are downloaded
+            e.g. by imap-backup.
+        - `status` - By default, an account is "active" and will be backed up when you run the backup command.
+            You can set this to "archived" if you want to stop running backups, but allow it to be migrated to a new server in the future using the `copy` command.
+            Otherwise, you can set this to "offline" if you want to just keep the account's backup on disk.
     global_options:
       title: "Global Options"
       description: "These settings affect all accounts."
-      choose_action: "Choose an action"
       change_download_strategy: "change download strategy (currently: '%{current}')"
-      return_to_main_menu: "(q) return to main menu"
+      help: "help"
+      help_text: |
+        This screen allows you to configure settings that affect all accounts.
+
+        Available global options:
+        - `download strategy` - This setting determines how often data is written to disk during backups.
+            The default setting ("delay writing metadata") is faster and less wearing on the disk,
+            while "write straight to disk" uses less memory and is suitable for devices with limited memory.
+            Choose the option for more details on the differences between these strategies.
       download_strategy_chooser:
         title: "Choose a Download Strategy"
         current_marker: " <- current"
@@ -68,7 +118,7 @@ en:
           messages and a .imap file with metadata like message lengths and their
           offsets within the .mbox file.
 
-          # write straight to disk
+          # 'write straight to disk'
 
           With this setting, each message and its metadata are written to disk
           as they are downloaded.
@@ -76,7 +126,7 @@ en:
           This choice uses least memory and so is suitable for backing up onto
           devices with limited memory, like Raspberry Pis.
 
-          # delay writing metadata
+          # 'delay writing metadata'
 
           This is the default setting.
 
@@ -92,8 +142,6 @@ en:
 
           Another configuration which affects backup performance is the
           `multi_fetch_size` account-level setting.
-        press_key: "Press a key "
-        return_to_main_menu: "(q) return to main menu"
     asker:
       email_prompt: "email address: "
       email_validation_error: "Enter a valid email address "
@@ -103,8 +151,16 @@ en:
     folder_chooser:
       title: "Add/remove folders"
       select_folder: "Select a folder (toggles)"
+      help: "help"
+      help_text: |
+        Use this screen to select which folders to backup.
+
+        Click a folder to toggle its backup status:
+        - Folders marked with '+' will be backed up
+        - Folders marked with '-' will not be backed up
+
+        If you don't select any folders, all folders will be backed up.
       return_to_account_menu: "(q) return to the account menu"
-      press_key: "Press a key "
       unable_to_get_folder_list: "Unable to get folder list"
       folders_removed: "The following folders have been removed: %{folders}"
       connection_failed: "Connection failed"
@@ -122,6 +178,7 @@ en:
     local:
       check:
         account: "Account: %{account}"
+      folder_not_found: "Folder '%{folder}' not found"
     remote:
       namespaces:
         name: "Name"
@@ -148,10 +205,6 @@ en:
       erb_syntax_error: "ERB template has syntax error: %{message}"
       erb_processing_error: "Error processing ERB template: %{message}"
       erb_invalid_json: "ERB template rendered invalid JSON: %{message}"
-    local:
-      check:
-        account: "Account: %{account}"
-      folder_not_found: "Folder '%{folder}' not found"
     utils:
       thunderbird_profile_not_found: "Thunderbird profile '%{profile}' not found"
       default_thunderbird_profile_not_found: "Default Thunderbird profile not found"

data/lib/imap/backup/locales/it.yml

@@ -1,62 +1,109 @@
 ---
 it:
   setup:
+    return_to_main_menu: "(q) torna al menu principale"
+    press_key: "Premi un tasto "
+    choose_action: "Scegli un'azione"
     main_menu:
       title: "Menu Principale"
-      choose_action: "Scegli un'azione"
       add_account: "aggiungi account"
       modify_global_options: "modifica opzioni globali"
+      help: "aiuto"
+      help_text: |
+        imap-backup ti aiuta a fare il backup e il ripristino dei tuoi account email.
+
+        Da questo menu principale, puoi:
+        - Aggiungere nuovi account email da cui fare il backup
+        - Modificare le impostazioni degli account esistenti
+        - Modificare le opzioni globali
       save_and_exit: "salva ed esci"
       exit_without_saving: "esci senza salvare le modifiche"
       quit: "(q) esci"
     account:
       title: "Account"
-      choose_action: "Scegli un'azione"
+      email: "email"
+      password: "password"
+      password_unset: "(non impostato)"
+      server: "server"
+      connection_options: "opzioni di connessione"
+      mode: "modalità"
+      mirror_emails: "modalità 'mirror'"
+      keep_all_emails: "modalità 'keep'"
+      path: "percorso di backup"
+      exclude: "escludi"
+      include: "includi"
+      all_folders: "(tutte le cartelle)"
+      no_folders_warning: "(tutte le cartelle) <- hai scelto di non fare il backup di nessuna cartella!"
+      multi_fetch: "multi-fetch"
+      reset_seen_flags_message: "le modifiche ai flag 'UNSEEN' verranno ripristinate durante il download"
+      status: "stato"
+      connection_configuration: "Configurazione della connessione"
       modify_email: "modifica email"
       modify_password: "modifica password"
+      modify_server: "modifica server"
+      server_prompt: "server: "
+      modify_connection_options: "modifica opzioni di connessione"
+      connection_options_prompt: "opzioni di connessione (in formato JSON): "
+      malformed_json: "JSON malformato, riprova"
+      test_connection: "testare connessione"
+      backup_configuration: "Configurazione backup"
+      toggle_mirror_mode: "attiva/disattiva modalità ('keep'/'mirror')"
       modify_backup_path: "modifica percorso di backup"
       toggle_folder_blacklist: "attiva/disattiva modalità di inclusione cartelle (whitelist/blacklist)"
       choose_folders: "scegli cartelle da %{action}"
       exclude_from_backups: "escludere dai backup"
       include_in_backups: "includere nei backup"
-      toggle_mirror_mode: "attiva/disattiva modalità ('keep'/'mirror')"
       modify_multi_fetch_size: "modifica dimensione multi-fetch (numero di email da scaricare alla volta)"
       size_prompt: "dimensione: "
-      modify_server: "modifica server"
-      server_prompt: "server: "
-      modify_connection_options: "modifica opzioni di connessione"
-      connection_options_prompt: "opzioni di connessione (in formato JSON): "
-      malformed_json: "JSON malformato, riprova"
-      press_key: "Premi un tasto "
       dont_fix_unread_flags: "non correggere modifiche ai flag 'UNSEEN' durante il download"
       fix_unread_flags: "correggi modifiche ai flag 'UNSEEN' durante il download"
       change_status: "cambia stato (%{current} -> %{next})"
-      test_connection: "testare la connessione"
+      danger_area: "Area pericolosa"
       delete: "elimina"
       delete_confirm: "Sei sicuro? (y/n) "
-      return_to_main_menu: "(q) torna al menu principale"
-      email: "email"
-      password: "password"
-      unset: "(non impostato)"
-      path: "percorso"
-      exclude: "escludi"
-      include: "includi"
-      all_folders: "(tutte le cartelle)"
-      no_folders_warning: "(tutte le cartelle) <- hai scelto di non fare il backup di nessuna cartella!"
-      mirror_emails: "modalità 'mirror'"
-      keep_all_emails: "modalità 'keep'"
-      mode: "modalità"
-      multi_fetch: "multi-fetch"
-      server: "server"
-      connection_options: "opzioni di connessione"
-      reset_seen_flags_message: "le modifiche ai flag 'UNSEEN' verranno ripristinate durante il download"
-      status: "stato"
+      other_actions: "Altre azioni"
+      help: "aiuto"
+      help_text: |
+        Questa schermata ti permette di configurare le impostazioni per un singolo account email.
+
+        Configurazione della connessione:
+        - `email` e `password` - Le credenziali per l'account
+        - `server` - Il server a cui connettersi per questo account. Non sarà necessario impostarlo se si utilizza
+            uno dei seguenti: GMail, Apple Mail, FastMail, PurelyMail.
+            Altrimenti, sarà necessario impostarlo sul server IMAP del provider di posta elettronica.
+        - `connection_options` - (Impostazione avanzata) Questa configurazione consente di specificare opzioni aggiuntive per la connessione IMAP.
+            Deve essere un oggetto JSON con chiavi corrispondenti alle opzioni descritte nella documentazione della libreria standard Ruby `net/imap`:
+            https://ruby-doc.org/stdlib-3.2/libdoc/net/imap/rdoc/Net/IMAP.html#initialize-instance_method
+            Ad esempio, se il server utilizza SSL ma ha un certificato non valido, è possibile impostare questa opzione su `{"ssl": {"verify_mode": "none"}}`.
+
+        Puoi testare se le impostazioni di connessione sono corrette selezionando l'opzione "testare connessione".
+
+        Configurazione del backup:
+        - `mode` - "modalità 'keep'" significa che le email eliminate dal server saranno comunque conservate nel backup,
+            mentre "modalità 'mirror'" significa che le email eliminate dal server saranno anche eliminate dal backup.
+        - `backup path` - La directory sul tuo computer locale dove verrà memorizzato il backup per questo account.
+        - `modalità di inclusione cartelle` - Questa opzione ti permette di scegliere se specificare le cartelle da *includere* nei backup
+            (modalità whitelist) o da *escludere* dai backup (modalità blacklist).
+            In modalità whitelist, cominci con tutte le cartelle escluse e puoi scegliere di includere solo quelle di cui vuoi fare il backup.
+            In modalità blacklist, cominci con tutte le cartelle incluse e puoi scegliere di escludere solo quelle di cui non vuoi fare il backup.
+        - `multi-fetch` - Questa opzione ti permette di configurare quanti messaggi scaricare alla volta durante i backup.
+        - `stato` - Questa opzione ti permette di modificare lo stato dell'account tra "active", "archived" e "offline".
+             Un account attivo ("active") è un account normale che viene incluso nei backup regolari.
+             Un account archiviato ("archived") è un account che non viene incluso nei backup regolari, ma i cui dati rimangono intatti su disco e possono essere migrati a un nuovo server in futuro usando il comando `copy`.
+             Un account offline ("offline") è un account che non viene incluso nei backup regolari e i cui dati vengono mantenuti su disco, ma non può essere migrato a un nuovo server in futuro usando il comando `copy`.
     global_options:
       title: "Opzioni Globali"
       description: "Queste impostazioni influenzano tutti gli account."
-      choose_action: "Scegli un'azione"
       change_download_strategy: "cambia strategia di download (attualmente: '%{current}')"
-      return_to_main_menu: "(q) torna al menu principale"
+      help: "aiuto"
+      help_text: |
+        Questa schermata ti permette di configurare le impostazioni che influenzano tutti gli account.
+
+        Opzioni globali disponibili:
+        - `strategia di download` - Questa impostazione determina la frequenza con cui i dati vengono scritti su disco durante i backup.
+            L'impostazione predefinita ("ritarda la scrittura dei metadati") è più veloce e consuma meno il disco,
+            mentre "scrivi direttamente su disco" utilizza meno memoria ed è adatta per dispositivi con memoria limitata.
+            Scegli l'opzione per maggiori dettagli sulle differenze tra queste strategie.
       download_strategy_chooser:
         title: "Scegli una Strategia di Download"
         current_marker: " <- attuale"
@@ -69,7 +116,7 @@ it:
           effettivi e un file .imap con metadati come le lunghezze dei messaggi e
           i loro offset all'interno del file .mbox.
 
-          # scrivi direttamente su disco
+          # 'scrivi direttamente su disco'
 
           Con questa impostazione, ogni messaggio e i suoi metadati vengono scritti
           su disco man mano che vengono scaricati.
@@ -77,7 +124,7 @@ it:
           Questa scelta utilizza meno memoria ed è quindi adatta per fare backup su
           dispositivi con memoria limitata, come i Raspberry Pi.
 
-          # ritarda la scrittura dei metadati
+          # 'ritarda la scrittura dei metadati'
 
           Questa è l'impostazione predefinita.
 
@@ -93,19 +140,25 @@ it:
 
           Un'altra configurazione che influisce sulle prestazioni del backup è
           l'impostazione `multi_fetch_size` a livello di account.
-        press_key: "Premi un tasto "
-        return_to_main_menu: "(q) torna al menu principale"
     asker:
       email_prompt: "indirizzo email: "
       email_validation_error: "Inserisci un indirizzo email valido "
       password_prompt: "password: "
       password_confirmation_prompt: "ripeti password: "
-      password_mismatch: "la password e la conferma non corrispondono.\nContinuare? (s/n) "
+      password_mismatch: "la password e la conferma non corrispondono.\nContinuare? (y/n) "
     folder_chooser:
       title: "Aggiungi/rimuovi cartelle"
       select_folder: "Seleziona una cartella (attiva/disattiva)"
+      help: "aiuto"
+      help_text: |
+        Utilizza questa schermata per selezionare quali cartelle eseguire il backup.
+
+        Clicca su una cartella per attivare/disattivare il suo stato di backup:
+        - Le cartelle contrassegnate con '+' verranno salvate
+        - Le cartelle contrassegnate con '-' non verranno salvate
+
+        Se non selezioni alcuna cartella, tutte le cartelle verranno salvate.
       return_to_account_menu: "(q) torna al menu account"
-      press_key: "Premi un tasto "
       unable_to_get_folder_list: "Impossibile ottenere l'elenco delle cartelle"
       folders_removed: "Le seguenti cartelle sono state rimosse: %{folders}"
       connection_failed: "Connessione fallita"
@@ -123,6 +176,7 @@ it:
     local:
       check:
         account: "Account: %{account}"
+      folder_not_found: "Cartella '%{folder}' non trovata"
     remote:
       namespaces:
         name: "Nome"
@@ -149,10 +203,6 @@ it:
       erb_syntax_error: "Il template ERB ha un errore di sintassi: %{message}"
       erb_processing_error: "Errore durante l'elaborazione del template ERB: %{message}"
       erb_invalid_json: "Il template ERB ha generato JSON non valido: %{message}"
-    local:
-      check:
-        account: "Account: %{account}"
-      folder_not_found: "Cartella '%{folder}' non trovata"
     utils:
       thunderbird_profile_not_found: "Profilo Thunderbird '%{profile}' non trovato"
       default_thunderbird_profile_not_found: "Profilo Thunderbird predefinito non trovato"

data/lib/imap/backup/setup/account/header.rb

@@ -39,7 +39,7 @@ module Imap::Backup
 
         #{format_rows(rows)}
 
-        #{I18n.t('setup.account.choose_action')}
+        #{I18n.t('setup.account.connection_configuration')}
       HEADER
     end
 
@@ -59,7 +59,7 @@ module Imap::Backup
     def password
       masked_password =
         if (account.password == "") || account.password.nil?
-          I18n.t("setup.account.unset")
+          I18n.t("setup.account.password_unset")
         else
           account.password.gsub(/./, "x")
         end

data/lib/imap/backup/setup/account.rb

@@ -58,7 +58,8 @@ module Imap::Backup
         toggle_reset_seen_flags_after_fetch menu
         rotate_status menu
         delete_account menu
-        menu.choice(I18n.t("setup.account.return_to_main_menu")) { throw :done }
+        show_help menu
+        menu.choice(I18n.t("setup.return_to_main_menu")) { throw :done }
         menu.hidden("quit") { throw :done }
       end
     end
@@ -81,6 +82,45 @@ module Imap::Backup
       end
     end
 
+    def modify_server(menu)
+      menu.choice(I18n.t("setup.account.modify_server")) do
+        server = highline.ask(I18n.t("setup.account.server_prompt"))
+        account.server = server if !server.nil?
+      end
+    end
+
+    def modify_connection_options(menu)
+      menu.choice(I18n.t("setup.account.modify_connection_options")) do
+        connection_options = highline.ask(I18n.t("setup.account.connection_options_prompt"))
+        if !connection_options.nil?
+          begin
+            account.connection_options = connection_options
+          rescue JSON::ParserError
+            Kernel.puts I18n.t("setup.account.malformed_json")
+            highline.ask I18n.t("setup.press_key")
+          end
+        end
+      end
+    end
+
+    def test_connection(menu)
+      text = "#{I18n.t('setup.account.test_connection')}\n\n" \
+             "#{I18n.t('setup.account.backup_configuration')}:"
+      menu.choice(text) do
+        result = Setup::ConnectionTester.new(account).test
+        Kernel.puts result
+        highline.ask I18n.t("setup.press_key")
+      end
+    end
+
+    def toggle_mirror_mode(menu)
+      menu_item = I18n.t("setup.account.toggle_mirror_mode")
+      new_value = account.mirror_mode ? nil : true
+      menu.choice(menu_item) do
+        account.mirror_mode = new_value
+      end
+    end
+
     def modify_backup_path(menu)
       menu.choice(I18n.t("setup.account.modify_backup_path")) do
         Setup::BackupPath.new(account: account, config: config).run
@@ -103,14 +143,6 @@ module Imap::Backup
       end
     end
 
-    def toggle_mirror_mode(menu)
-      menu_item = I18n.t("setup.account.toggle_mirror_mode")
-      new_value = account.mirror_mode ? nil : true
-      menu.choice(menu_item) do
-        account.mirror_mode = new_value
-      end
-    end
-
     def modify_multi_fetch_size(menu)
       menu.choice(I18n.t("setup.account.modify_multi_fetch_size")) do
         size = highline.ask(I18n.t("setup.account.size_prompt"))
@@ -119,27 +151,6 @@ module Imap::Backup
       end
     end
 
-    def modify_server(menu)
-      menu.choice(I18n.t("setup.account.modify_server")) do
-        server = highline.ask(I18n.t("setup.account.server_prompt"))
-        account.server = server if !server.nil?
-      end
-    end
-
-    def modify_connection_options(menu)
-      menu.choice(I18n.t("setup.account.modify_connection_options")) do
-        connection_options = highline.ask(I18n.t("setup.account.connection_options_prompt"))
-        if !connection_options.nil?
-          begin
-            account.connection_options = connection_options
-          rescue JSON::ParserError
-            Kernel.puts I18n.t("setup.account.malformed_json")
-            highline.ask I18n.t("setup.account.press_key")
-          end
-        end
-      end
-    end
-
     def toggle_reset_seen_flags_after_fetch(menu)
       menu_item =
         if account.reset_seen_flags_after_fetch
@@ -165,26 +176,30 @@ module Imap::Backup
         current: current_status,
         next: next_status
       )
-      menu.choice(menu_item) do
+      following_section = I18n.t("setup.account.danger_area")
+      text = "#{menu_item}\n\n#{following_section}:"
+      menu.choice(text) do
         account.status = next_status
       end
     end
 
-    def test_connection(menu)
-      menu.choice(I18n.t("setup.account.test_connection")) do
-        result = Setup::ConnectionTester.new(account).test
-        Kernel.puts result
-        highline.ask I18n.t("setup.account.press_key")
-      end
-    end
-
     def delete_account(menu)
-      menu.choice(I18n.t("setup.account.delete")) do
+      menu_item = I18n.t("setup.account.delete")
+      following_section = I18n.t("setup.account.other_actions")
+      text = "#{menu_item}\n\n#{following_section}:"
+      menu.choice(text) do
         if highline.agree(I18n.t("setup.account.delete_confirm"))
           account.mark_for_deletion
           throw :done
         end
       end
     end
+
+    def show_help(menu)
+      menu.choice(I18n.t("setup.account.help")) do
+        Kernel.puts I18n.t("setup.account.help_text")
+        highline.ask I18n.t("setup.press_key")
+      end
+    end
   end
 end

data/lib/imap/backup/setup/folder_chooser.rb

@@ -16,13 +16,13 @@ module Imap::Backup
     # @return [void]
     def run
       if client.nil?
-        highline.ask I18n.t("setup.folder_chooser.press_key")
+        highline.ask I18n.t("setup.press_key")
         return
       end
 
       if folder_names.empty?
         Logger.logger.warn I18n.t("setup.folder_chooser.unable_to_get_folder_list")
-        highline.ask I18n.t("setup.folder_chooser.press_key")
+        highline.ask I18n.t("setup.press_key")
         return
       end
 
@@ -49,6 +49,7 @@ module Imap::Backup
         MENU
         menu.index = :number
         add_folders menu
+        show_help menu
         menu.choice(I18n.t("setup.folder_chooser.return_to_account_menu")) { throw :done }
         menu.hidden("quit") { throw :done }
       end
@@ -63,6 +64,13 @@ module Imap::Backup
       end
     end
 
+    def show_help(menu)
+      menu.choice(I18n.t("setup.folder_chooser.help")) do
+        Kernel.puts I18n.t("setup.folder_chooser.help_text")
+        highline.ask I18n.t("setup.press_key")
+      end
+    end
+
     def selected?(folder_name)
       account_folders.find { |f| f == folder_name }
     end
@@ -85,7 +93,7 @@ module Imap::Backup
 
       Kernel.puts I18n.t("setup.folder_chooser.folders_removed", folders: removed.join(", "))
 
-      highline.ask I18n.t("setup.folder_chooser.press_key")
+      highline.ask I18n.t("setup.press_key")
     end
 
     def toggle_selection(folder_name)

data/lib/imap/backup/setup/global_options/download_strategy_chooser.rb

@@ -42,7 +42,7 @@ class Imap::Backup::Setup::GlobalOptions
           end
         end
         show_help menu
-        menu.choice(I18n.t("setup.global_options.download_strategy_chooser.return_to_main_menu")) do
+        menu.choice(I18n.t("setup.return_to_main_menu")) do
           throw :done
         end
         menu.hidden("quit") { throw :done }
@@ -52,7 +52,7 @@ class Imap::Backup::Setup::GlobalOptions
     def show_help(menu)
       menu.choice(I18n.t("setup.global_options.download_strategy_chooser.help")) do
         Kernel.puts I18n.t("setup.global_options.download_strategy_chooser.help_text")
-        highline.ask I18n.t("setup.global_options.download_strategy_chooser.press_key")
+        highline.ask I18n.t("setup.press_key")
       end
     end
 

data/lib/imap/backup/setup/global_options.rb

@@ -35,10 +35,11 @@ module Imap::Backup
 
           #{I18n.t('setup.global_options.description')}
 
-          #{I18n.t('setup.global_options.choose_action')}
+          #{I18n.t('setup.choose_action')}
         MENU
         change_download_strategy menu
-        menu.choice(I18n.t("setup.global_options.return_to_main_menu")) { throw :done }
+        show_help menu
+        menu.choice(I18n.t("setup.return_to_main_menu")) { throw :done }
         menu.hidden("quit") { throw :done }
       end
     end
@@ -57,6 +58,13 @@ module Imap::Backup
       end
     end
 
+    def show_help(menu)
+      menu.choice(I18n.t("setup.global_options.help")) do
+        Kernel.puts I18n.t("setup.global_options.help_text")
+        highline.ask I18n.t("setup.press_key")
+      end
+    end
+
     def highline
       Imap::Backup::Setup.highline
     end

data/lib/imap/backup/setup.rb

@@ -44,11 +44,12 @@ module Imap::Backup
         menu.header = <<~MENU.chomp
           #{helpers.title_prefix} #{I18n.t('setup.main_menu.title')}
 
-          #{I18n.translate('setup.main_menu.choose_action')}
+          #{I18n.t('setup.choose_action')}
         MENU
         account_items menu
         add_account_item menu
         modify_global_options menu
+        show_help menu
         if config.modified?
           menu.choice(I18n.t("setup.main_menu.save_and_exit")) do
             config.save
@@ -88,6 +89,13 @@ module Imap::Backup
       end
     end
 
+    def show_help(menu)
+      menu.choice(I18n.t("setup.main_menu.help")) do
+        Kernel.puts I18n.t("setup.main_menu.help_text")
+        self.class.highline.ask I18n.t("setup.press_key")
+      end
+    end
+
     def default_account_config(username)
       Imap::Backup::Account.new(
         username: username,

data/lib/imap/backup/translator.rb

@@ -20,8 +20,10 @@ module Imap::Backup
     private
 
     def locale_files
-      locales_path = File.expand_path("locales", __dir__)
-      Dir.glob(File.join(locales_path, "*.yml"))
+      @locale_files ||= begin
+        path = File.expand_path("locales", __dir__)
+        Dir.glob(File.join(path, "*.yml"))
+      end
     end
 
     def detect_locale
@@ -40,9 +42,10 @@ module Imap::Backup
     end
 
     def available_locales
-      locale_files.map do |file|
-        File.basename(file, ".yml").to_sym
-      end
+      @available_locales ||=
+        locale_files.map do |file|
+          File.basename(file, ".yml").to_sym
+        end
     end
   end
 end

data/lib/imap/backup/version.rb

@@ -4,7 +4,7 @@ module Imap::Backup
   # @private
   MAJOR    = 16
   # @private
-  MINOR    = 5
+  MINOR    = 6
   # @private
   REVISION = 0
   # @private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 16.5.0
+  version: 16.6.0
 platform: ruby
 authors:
 - Joe Yates
@@ -253,6 +253,7 @@ files:
 - lib/imap/backup/file_mode.rb
 - lib/imap/backup/flag_refresher.rb
 - lib/imap/backup/local_only_message_deleter.rb
+- lib/imap/backup/locales/de.yml
 - lib/imap/backup/locales/en.yml
 - lib/imap/backup/locales/it.yml
 - lib/imap/backup/lockfile.rb