imap-backup 16.4.2 → 16.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc471fce2bd514e0eee4cec922e8f368df0b2fb99f8b89b2d852e07799a2be77
-  data.tar.gz: fd563c2ee648d5e384a10cdfc79a7d1d5be128bdce5908711396d414c801173f
+  metadata.gz: 325c46cce0eff42c96d4c44e686b32f0d52352cdfa038c17a132069b71bdf11e
+  data.tar.gz: 349426301b37fa38db3da6c2d71a3979892345828b88ffa2b52752a559f6a95b
 SHA512:
-  metadata.gz: 36088caab383a7ff2528d8ad83813f58918abda4d80a56b0f2b2f1f45d5fc840934d1bc31e1907de11cc665f5aecb5b12152bb8dee686fb656294eb55440897e
-  data.tar.gz: 389a82b7755342dd591fd0e2d45d760eb8350f697d46414d8d90776624bd0ee7263acfe163ab1e8dd42c869d12a544c2d5faa4656d4ef5c802f4991b9f33c1b4
+  metadata.gz: 6c4735412c68747d5365048e7748cc849bb1302a2da6e4af60354bf2a44c3c4dab5f14cf9ea7111cd7c6f416faea8ad429657a551755167662998e20ff7aae3a
+  data.tar.gz: 213bc6df849b8e7d72ded14920695e1a158d8657ac0d3bcd6632068f0c76258d2b5d0f37a5073867cf1f549249b1a2df651a0327ce803051311ed33fe5e757a0

data/bin/imap-backup

@@ -11,6 +11,9 @@ end
 
 require "imap/backup/cli"
 require "imap/backup/logger"
+require "imap/backup/translator"
+
+Imap::Backup::Translator.new.setup
 
 Imap::Backup::Logger.sanitize_stderr do
   Imap::Backup::CLI.start(ARGV)

data/docs/TODO.md

@@ -0,0 +1,35 @@
+# Add Internationalization (i18n) Support
+
+Status: [x]
+
+## Description
+
+Add internationalization support to make imap-backup accessible to non-English-speaking users. The primary focus should be on the menu-driven setup interface, which contains the most user-facing text. This will allow the application to display messages and prompts in the user's preferred language based on locale environment variables (LANGUAGE, LANG, LC_*).
+
+## Technical Specifics
+
+- Use the `locale` and `i18n` gems
+- Override the `locale` gem's behaviour when LANG=C (use `:en`)
+- Store translations under `lib/imap/backup/locales`
+- 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

@@ -0,0 +1,153 @@
+# Internationalization (i18n)
+
+imap-backup supports multiple languages through internationalization (i18n). This document explains how the system works and how to contribute translations.
+
+## Overview
+
+The application automatically detects the user's preferred language from environment variables and displays messages in that language. English is the default fallback language.
+
+## How Locale Detection Works
+
+The i18n system uses the `locale` gem to detect the user's preferred language by checking these environment variables in order:
+
+1. `LANGUAGE`
+2. `LANG`
+3. `LC_ALL`
+4. `LC_MESSAGES`
+5. Other `LC_*` variables
+
+Special case: When `LANG=C` is set (common in minimal environments), the system uses English (`:en`).
+
+The system selects the first detected locale that has a translation file available.
+
+## Translation Files
+
+Translation files are stored in YAML format at:
+
+```
+lib/imap/backup/locales/
+```
+
+Each language has its own file named with the ISO 639-1 language code:
+
+- `en.yml` - English (default)
+- `it.yml` - Italian
+
+## File Structure
+
+Translation files use a hierarchical structure with nested keys. Here's an example:
+
+```yaml
+---
+en:
+  setup:
+    choose_action: "Choose an action"
+    main_menu:
+      title: "Main Menu"
+      add_account: "add account"
+```
+
+### Using Translations in Code
+
+Translations are accessed using the `I18n.t` method with dot-separated keys:
+
+```ruby
+I18n.t("setup.main_menu.title")  # => "Main Menu"
+```
+
+### Interpolation
+
+Some strings include variables using the `%{variable}` syntax:
+
+```yaml
+en:
+  setup:
+    account:
+      choose_folders: "choose folders to %{action}"
+```
+
+In code:
+
+```ruby
+I18n.t("setup.account.choose_folders", action: "backup")
+# => "choose folders to backup"
+```
+
+## Contributing Translations
+
+### Adding a New Language
+
+To add support for a new language:
+
+1. **Create a new locale file** in `lib/imap/backup/locales/` using the ISO 639-1 language code (e.g., `fr.yml` for French).
+
+2. **Copy the structure from `en.yml`** to ensure all keys are present:
+
+   ```yaml
+   ---
+   fr:
+     setup:
+       choose_action: "Choisissez une action"
+       main_menu:
+         title: "Menu Principal"
+         # ... continue translating all keys
+   ```
+
+3. **Translate all strings** while keeping:
+   - The YAML structure unchanged
+   - All interpolation variables like `%{action}` in their original form
+   - Special formatting like keyboard shortcuts in their original form (e.g., `(q)`)
+
+4. **Test your translations** by setting the appropriate locale:
+
+   ```sh
+   LANG=fr_FR.UTF-8 imap-backup setup
+   ```
+
+5. **Submit a pull request** with your new translation file.
+
+### Updating Existing Translations
+
+When updating translations:
+
+1. Compare your language file with `en.yml` to identify missing or changed keys
+2. Add or update the necessary translations
+3. Ensure the structure matches the current `en.yml` structure
+4. Test with your locale settings
+5. Submit a pull request
+
+## Translation Guidelines
+
+- **Maintain context**: Keep in mind where text appears (menus, prompts, error messages)
+- **Preserve formatting**: Keep special characters like `(q)` for keyboard shortcuts
+- **Keep variables**: Don't translate interpolation variables like `%{action}`
+- **Test thoroughly**: Run the setup interface to ensure translations fit properly
+- **Be consistent**: Use consistent terminology throughout the translation
+- **Follow conventions**: Respect language-specific conventions for punctuation and spacing
+
+## Current Language Support
+
+- **English (en)**: Complete (reference implementation)
+- **Italian (it)**: Complete
+
+## Testing Translations
+
+To test translations in your local environment:
+
+```sh
+# Test with a specific locale
+LANG=it_IT.UTF-8 imap-backup setup
+
+# Test with fallback to English
+LANG=C imap-backup setup
+```
+
+## Need Help?
+
+If you have questions about contributing translations:
+
+- Check existing translation files (`en.yml` and `it.yml`) for examples
+- Open an issue on GitHub to discuss translation conventions
+- Ask for clarification on ambiguous strings
+
+Thank you for helping make imap-backup accessible to users worldwide!

data/imap-backup.gemspec

@@ -13,6 +13,7 @@ Gem::Specification.new do |gem|
   gem.files         = %w[bin/imap-backup]
   gem.files         += Dir.glob("docs/*.md")
   gem.files         += Dir.glob("lib/**/*.rb")
+  gem.files         += Dir.glob("lib/imap/backup/locales/*.yml")
   gem.files         += %w[imap-backup.gemspec]
   gem.files         += %w[LICENSE README.md]
 
@@ -21,6 +22,8 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = ">= 3.2"
 
   gem.add_dependency "highline"
+  gem.add_dependency "i18n"
+  gem.add_dependency "locale"
   gem.add_dependency "logger"
   gem.add_dependency "mail", "2.7.1"
   gem.add_dependency "net-imap", ">= 0.3.2"

data/lib/imap/backup/cli/helpers.rb

@@ -72,9 +72,7 @@ module Imap::Backup
       erb_config_path = options[:erb_configuration]
 
       # Check mutual exclusivity
-      if config_path && erb_config_path
-        raise "Cannot specify both --config and --erb-configuration options"
-      end
+      raise I18n.t("cli.helpers.config_mutual_exclusivity") if config_path && erb_config_path
 
       # Handle ERB configuration
       return load_erb_config(erb_config_path, options) if erb_config_path
@@ -86,7 +84,7 @@ module Imap::Backup
         exists = Configuration.exist?(path: path)
         if !exists
           expected = path || Configuration.default_pathname
-          raise ConfigurationNotFound, "Configuration file '#{expected}' not found"
+          raise ConfigurationNotFound, I18n.t("cli.helpers.config_not_found", path: expected)
         end
       end
       Configuration.new(path: path)
@@ -96,7 +94,7 @@ module Imap::Backup
     # @return [Account] the Account information for the email address
     def account(config, email)
       account = config.accounts.find { |a| a.username == email }
-      raise "#{email} is not a configured account" if !account
+      raise I18n.t("cli.helpers.account_not_configured", email: email) if !account
 
       account
     end
@@ -123,7 +121,7 @@ module Imap::Backup
     def load_erb_config(erb_path, _options)
       # Check if file exists
       unless File.exist?(erb_path)
-        raise ConfigurationNotFound, "ERB configuration file '#{erb_path}' not found"
+        raise ConfigurationNotFound, I18n.t("cli.helpers.erb_config_not_found", path: erb_path)
       end
 
       begin
@@ -132,16 +130,16 @@ module Imap::Backup
         erb = ERB.new(erb_content)
         rendered_json = erb.result
       rescue SyntaxError => e
-        raise "ERB template has syntax error: #{e.message}"
+        raise I18n.t("cli.helpers.erb_syntax_error", message: e.message)
       rescue StandardError => e
-        raise "Error processing ERB template: #{e.message}"
+        raise I18n.t("cli.helpers.erb_processing_error", message: e.message)
       end
 
       # Validate rendered JSON
       begin
         JSON.parse(rendered_json)
       rescue JSON::ParserError => e
-        raise "ERB template rendered invalid JSON: #{e.message}"
+        raise I18n.t("cli.helpers.erb_invalid_json", message: e.message)
       end
 
       # Create temporary file with rendered JSON

data/lib/imap/backup/cli/local/check.rb

@@ -64,7 +64,7 @@ module Imap::Backup
 
     def print_check_results_as_text(results)
       results.each do |account_results|
-        Kernel.puts "Account: #{account_results[:account]}"
+        Kernel.puts I18n.t("cli.local.check.account", account: account_results[:account])
         account_results[:folders].each do |folder_results|
           Kernel.puts "\t#{folder_results[:name]}: #{folder_results[:result]}"
         end

data/lib/imap/backup/cli/local.rb

@@ -95,7 +95,7 @@ module Imap::Backup
       serializer, _folder = serialized_folders.find do |_s, f|
         f.name == folder_name
       end
-      raise "Folder '#{folder_name}' not found" if !serializer
+      raise I18n.t("cli.local.folder_not_found", folder: folder_name) if !serializer
 
       case options[:format]
       when "json"
@@ -126,7 +126,7 @@ module Imap::Backup
       serializer, _folder = serialized_folders.find do |_s, f|
         f.name == folder_name
       end
-      raise "Folder '#{folder_name}' not found" if !serializer
+      raise I18n.t("cli.local.folder_not_found", folder: folder_name) if !serializer
 
       uid_list = uids.split(",")
 

data/lib/imap/backup/cli/remote.rb

@@ -115,7 +115,9 @@ module Imap::Backup
     def list_namespaces(namespaces)
       Kernel.puts format(
         NAMESPACE_TEMPLATE,
-        {name: "Name", prefix: "Prefix", delim: "Delimiter"}
+        {name: I18n.t("cli.remote.namespaces.name"),
+         prefix: I18n.t("cli.remote.namespaces.prefix"),
+         delim: I18n.t("cli.remote.namespaces.delimiter")}
       )
       list_namespace namespaces, :personal
       list_namespace namespaces, :other
@@ -127,7 +129,8 @@ module Imap::Backup
       if info
         Kernel.puts format(NAMESPACE_TEMPLATE, name: name, **info)
       else
-        Kernel.puts format("%-10<name>s (Not defined)", name: name)
+        Kernel.puts format("%-10<name>s %<not_defined>s",
+                           name: name, not_defined: I18n.t("cli.remote.namespaces.not_defined"))
       end
     end
 

data/lib/imap/backup/cli/restore.rb

@@ -38,7 +38,7 @@ module Imap::Backup
           account = account(config, email)
           restore(account, **restore_options)
         when email && options.key?(:accounts)
-          raise "Missing EMAIL parameter"
+          raise I18n.t("cli.restore.missing_email_parameter")
         when !email && options.key?(:accounts)
           Logger.logger.info(
             "Calling restore with the --account option is deprecated, " \

data/lib/imap/backup/cli/stats.rb

@@ -42,10 +42,10 @@ module Imap::Backup
     private
 
     TEXT_COLUMNS = [
-      {name: :folder, width: 20, alignment: :left},
-      {name: :remote, width: 8, alignment: :right},
-      {name: :both, width: 8, alignment: :right},
-      {name: :local, width: 8, alignment: :right}
+      {name: :folder, i18n_key: "cli.stats.folder", width: 20, alignment: :left},
+      {name: :remote, i18n_key: "cli.stats.remote", width: 8, alignment: :right},
+      {name: :both, i18n_key: "cli.stats.both", width: 8, alignment: :right},
+      {name: :local, i18n_key: "cli.stats.local", width: 8, alignment: :right}
     ].freeze
     ALIGNMENT_FORMAT_SYMBOL = {left: "-", right: " "}.freeze
     private_constant :TEXT_COLUMNS, :ALIGNMENT_FORMAT_SYMBOL
@@ -96,7 +96,7 @@ module Imap::Backup
 
     def text_header
       titles = TEXT_COLUMNS.map do |column|
-        format("%-#{column[:width]}s", column[:name])
+        format("%-#{column[:width]}s", I18n.t(column[:i18n_key]))
       end.join("|")
 
       underline = TEXT_COLUMNS.map do |column|

data/lib/imap/backup/cli/transfer.rb

@@ -97,23 +97,24 @@ module Imap::Backup
     end
 
     def check_accounts!
-      if destination_email == source_email
-        raise "Source and destination accounts cannot be the same!"
-      end
+      raise I18n.t("cli.transfer.same_account_error") if destination_email == source_email
 
-      raise "Account '#{destination_email}' does not exist" if !destination_account
+      if !destination_account
+        raise I18n.t("cli.transfer.destination_not_found",
+                     email: destination_email)
+      end
 
-      raise "Account '#{source_email}' does not exist" if !source_account
+      raise I18n.t("cli.transfer.source_not_found", email: source_email) if !source_account
 
       if !source_account.available_for_migration?
-        raise "Account '#{source_email}' is not available for migration " \
-              "(status: #{source_account.status})"
+        raise I18n.t("cli.transfer.source_not_available",
+                     email: source_email, status: source_account.status)
       end
 
       return if destination_account.available_for_migration?
 
-      raise "Account '#{destination_email}' is not available for migration " \
-            "(status: #{destination_account.status})"
+      raise I18n.t("cli.transfer.destination_not_available",
+                   email: destination_email, status: destination_account.status)
     end
 
     def choose_prefixes_and_delimiters!
@@ -126,12 +127,10 @@ module Imap::Backup
     end
 
     def ensure_no_prefix_or_delimiter_parameters!
-      if destination_delimiter
-        raise "--automatic-namespaces is incompatible with --destination-delimiter"
-      end
-      raise "--automatic-namespaces is incompatible with --destination-prefix" if destination_prefix
-      raise "--automatic-namespaces is incompatible with --source-delimiter" if source_delimiter
-      raise "--automatic-namespaces is incompatible with --source-prefix" if source_prefix
+      raise I18n.t("cli.transfer.incompatible_destination_delimiter") if destination_delimiter
+      raise I18n.t("cli.transfer.incompatible_destination_prefix") if destination_prefix
+      raise I18n.t("cli.transfer.incompatible_source_delimiter") if source_delimiter
+      raise I18n.t("cli.transfer.incompatible_source_prefix") if source_prefix
     end
 
     def query_servers_for_settings

data/lib/imap/backup/cli/utils.rb

@@ -76,14 +76,17 @@ module Imap::Backup
       profile = thunderbird_profile(profile_name)
 
       if !profile
-        raise "Thunderbird profile '#{profile_name}' not found" if profile_name
+        if profile_name
+          raise I18n.t("cli.utils.thunderbird_profile_not_found",
+                       profile: profile_name)
+        end
 
-        raise "Default Thunderbird profile not found"
+        raise I18n.t("cli.utils.default_thunderbird_profile_not_found")
       end
 
       serialized_folders = Account::SerializedFolders.new(account: account)
 
-      raise "No serialized folders were found for account '#{email}'" if serialized_folders.none?
+      raise I18n.t("cli.utils.no_serialized_folders", email: email) if serialized_folders.none?
 
       serialized_folders.each_key do |serializer|
         Thunderbird::MailboxExporter.new(

data/lib/imap/backup/cli.rb

@@ -224,7 +224,7 @@ module Imap::Backup
     # Prints the program version
     # @return [void]
     def version
-      Kernel.puts "imap-backup #{Imap::Backup::VERSION}"
+      Kernel.puts I18n.t("cli.version", version: Imap::Backup::VERSION)
     end
   end
 end

data/lib/imap/backup/configuration.rb

@@ -16,10 +16,7 @@ module Imap::Backup
     # The default download strategy key
     DEFAULT_STRATEGY = "delay_metadata".freeze
     # The available download strategies
-    DOWNLOAD_STRATEGIES = [
-      {key: "direct", description: "write straight to disk"},
-      {key: DEFAULT_STRATEGY, description: "delay writing metadata"}
-    ].freeze
+    DOWNLOAD_STRATEGIES = ["direct", DEFAULT_STRATEGY].freeze
     # The current file version
     VERSION = "2.2".freeze
 
@@ -77,7 +74,7 @@ module Imap::Backup
       end
     end
 
-    # @return [String] the cofigured download strategy
+    # @return [String] the configured download strategy
     def download_strategy
       ensure_loaded!
 
@@ -87,7 +84,7 @@ module Imap::Backup
     # @param value [String] the new strategy
     # @return [void]
     def download_strategy=(value)
-      raise "Unknown strategy '#{value}'" if !DOWNLOAD_STRATEGIES.find { |s| s[:key] == value }
+      raise "Unknown strategy '#{value}'" if !DOWNLOAD_STRATEGIES.include?(value)
 
       ensure_loaded!
 
@@ -133,7 +130,7 @@ module Imap::Backup
           contents = File.read(pathname)
           data = JSON.parse(contents, symbolize_names: true)
           data[:download_strategy] =
-            if DOWNLOAD_STRATEGIES.find { |s| s[:key] == data[:download_strategy] }
+            if DOWNLOAD_STRATEGIES.include?(data[:download_strategy])
               data[:download_strategy]
             else
               DEFAULT_STRATEGY