Auction Card Translator

A WordPress plugin that translates Japanese car auction card images to English using Google Gemini AI (Nano Banana Pro) while preserving the original card design, layout, and formatting.

Features

• AI-Powered Translation — Uses Google Gemini 3 Pro Image (Nano Banana Pro) to translate Japanese text to English directly on the auction card image
• Design Preservation — Keeps the original card layout, colors, formatting, and design elements intact
• Drag & Drop Upload — Simple drag-and-drop or click-to-browse file upload interface
• Side-by-Side Comparison — View original and translated cards side by side with click-to-zoom
• Private Per-User Storage — Each user's translations are saved privately in the WordPress media library; other users cannot see them
• Translation History — Full history page in the WordPress dashboard with thumbnails, download links, and deletion
• Bulk Upload — Translate multiple auction cards at once (up to 10 per batch)
• Widget Support — Add the translator to any sidebar as a classic WordPress widget
• Shortcode Support — Embed the translator on any page or post with [auction_card_translator]
• Mobile Responsive — Fully responsive design that works on desktop, tablet, and mobile
• Secure — Nonce verification, capability checks, file validation, SQL injection prevention, and XSS protection throughout

Requirements

• WordPress 5.8 or higher
• PHP 7.4 or higher
• A Google Gemini API key (get one free)

Installation

From ZIP File

1. Download the latest auction-card-translator.zip from the Releases page
2. In your WordPress admin, go to Plugins > Add New > Upload Plugin
3. Select the ZIP file and click Install Now
4. Click Activate Plugin

Manual Installation

1. Download or clone this repository
2. Upload the auction-card-translator folder to /wp-content/plugins/
3. Activate the plugin through the Plugins menu in WordPress

Configuration

1. Get a Google Gemini API Key

1. Go to Google AI Studio
2. Sign in with your Google account
3. Click Create API Key
4. Copy the generated key

2. Configure the Plugin

1. In WordPress admin, go to Settings > ACT Settings
2. Paste your API key in the Gemini API Key field
3. Select your preferred model:
   • Gemini 3 Pro Image - Nano Banana Pro (Recommended) — Highest quality translations with advanced text rendering
   • Gemini 2.5 Flash Image - Nano Banana — Faster processing, higher free tier quota
4. Click Save Changes

Usage

Shortcode

Add the translator to any page or post using shortcodes:

[auction_card_translator]

With translation history displayed below the upload form:

[auction_card_translator show_history="true"]

With bulk upload enabled (multiple files at once):

[auction_card_translator bulk="true"]

Both options combined:

[auction_card_translator show_history="true" bulk="true"]

Widget

1. Go to Appearance > Widgets
2. Find Auction Card Translator in the available widgets
3. Drag it to your desired sidebar
4. Set a title and optionally enable bulk upload
5. Click Save

Translating an Auction Card

1. Navigate to the page with the translator
2. Drag and drop a Japanese auction card image onto the upload zone (or click to browse)
   • Supported formats: JPG, PNG, WebP
   • Maximum file size: 10MB
3. Wait for the translation to complete (typically 15-60 seconds)
4. View the side-by-side comparison of original and translated cards
5. Click Download Translated Image to save the result
6. Click Translate Another to process a new card

Viewing Translation History

• Go to My Translations in the WordPress admin sidebar
• Browse all your past translations with thumbnails and dates
• Click Download to save any translated image
• Click Delete to remove a translation and its associated files

Supported Image Formats

Format	Extension	Max Size
JPEG	.jpg, .jpeg	10MB
PNG	.png	10MB
WebP	.webp	10MB

API Quota & Pricing

Free Tier

• Nano Banana Pro (gemini-3-pro-image-preview): ~2-3 images per day
• Nano Banana (gemini-2.5-flash-image): Higher daily limit

Paid Tier

• Enable billing at Google AI Studio
• Approximately $0.02-0.04 per image translation
• See Gemini API Pricing for current rates

Security

This plugin follows WordPress security best practices:

• Authentication Required — All functionality requires a logged-in WordPress user. No public-facing AJAX endpoints (wp_ajax_nopriv_) are registered
• Nonce Verification — Every AJAX request is verified with WordPress nonces to prevent CSRF attacks
• User Isolation — All database queries enforce user ownership. Users can only view, download, and delete their own translations
• File Validation — Uploaded files are validated by MIME type check (wp_check_filetype_and_ext), actual content verification (getimagesize), and file size limit enforcement
• SQL Injection Prevention — All database queries use $wpdb->prepare() with parameterized queries
• Output Escaping — All output uses esc_html(), esc_attr(), esc_url(), and wp_kses() to prevent XSS
• Input Sanitization — All input is sanitized with sanitize_text_field(), absint(), and sanitize_file_name()
• Capability Checks — Settings page requires manage_options capability (administrators only)

File Structure

auction-card-translator/
├── auction-card-translator.php      # Main plugin file (bootstrap)
├── uninstall.php                     # Cleanup on plugin deletion
├── includes/
│   ├── class-act-activator.php      # Database table creation
│   ├── class-act-deactivator.php    # Deactivation cleanup
│   ├── class-act-loader.php         # Hook/filter registration
│   ├── class-act-i18n.php           # Internationalization
│   ├── class-act-encryption.php     # AES-256-CBC encryption utility
│   ├── class-act-gemini-client.php  # Google Gemini API client
│   ├── class-act-translation-db.php # Database CRUD operations
│   ├── class-act-file-handler.php   # File upload & media library
│   ├── class-act-widget.php         # WordPress widget
│   └── class-act-shortcode.php      # Shortcode handler
├── admin/
│   ├── class-act-admin.php          # Admin pages & settings
│   ├── class-act-admin-ajax.php     # Admin AJAX handlers
│   ├── partials/
│   │   ├── act-settings-page.php    # Settings page template
│   │   └── act-translations-page.php # History page template
│   ├── css/act-admin.css            # Admin styles
│   └── js/act-admin.js              # Admin JavaScript
├── public/
│   ├── class-act-public.php         # Frontend asset loading
│   ├── class-act-public-ajax.php    # Translation AJAX handler
│   ├── partials/
│   │   └── act-upload-form.php      # Upload form template
│   ├── css/act-public.css           # Frontend styles
│   └── js/
│       ├── act-upload.js            # Drag-drop & upload logic
│       └── act-comparison.js        # Image zoom/pan
├── assets/
│   └── spinner.svg                  # Loading animation
└── languages/
    └── auction-card-translator.pot  # Translation template

Database

The plugin creates one custom table on activation:

{prefix}act_translations

Column	Type	Description
id	bigint(20)	Primary key
user_id	bigint(20)	WordPress user ID
original_attachment_id	bigint(20)	Media library ID of original image
translated_attachment_id	bigint(20)	Media library ID of translated image
original_filename	varchar(255)	Original uploaded filename
status	varchar(20)	pending, processing, completed, or failed
error_message	text	Error details if translation failed
created_at	datetime	Record creation timestamp
updated_at	datetime	Last update timestamp

Uninstallation

When the plugin is deleted (not just deactivated) through WordPress admin, it automatically:

1. Drops the act_translations database table
2. Deletes all plugin options from wp_options
3. Removes all original and translated images from the media library
4. Cleans up all plugin-related post meta
5. Removes the plugin upload directory

Note: Deactivating the plugin does NOT delete any data. Data is only removed when you delete the plugin.

Troubleshooting

"API key not valid"

• Verify your key works by visiting: https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_KEY
• Make sure the Generative Language API is enabled in Google Cloud Console

"You exceeded your current quota"

• Free tier has limited daily image generations
• Switch to Nano Banana (gemini-2.5-flash-image) for higher free limits
• Or enable billing at Google AI Studio for pay-as-you-go

"No translated image was returned by the API"

• The model may have returned text only instead of an image
• Try submitting the image again
• Try switching between Nano Banana and Nano Banana Pro models

Translation takes too long

• Image generation typically takes 15-60 seconds
• The plugin has a 120-second timeout
• Large images may take longer; try resizing before upload

Plugin shows "plugin file does not exist" after upload

• Delete any leftover files from previous install attempts in wp-content/plugins/
• Re-upload the ZIP file through Plugins > Add New > Upload Plugin

Hooks & Filters

Developers can extend the plugin using these WordPress AJAX actions:

Hook	Description
wp_ajax_act_translate	Single image translation
wp_ajax_act_translate_bulk	Bulk image translation
wp_ajax_act_delete_translation	Delete a translation record

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -am 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

License

This project is licensed under the GPL v2 or later — see the LICENSE file for details.

Credits

• Google Gemini API for AI-powered image translation
• Built following the WordPress Plugin Boilerplate architecture