AI TranslatePress Translation Documentation

Plugin Name: AI TranslatePress Translation
Version: 2.7
Author: Granular Concept
Plugin URI: https://granularconcept.com/plugins/ai-translatepress-translation
Author URI: https://granularconcept.com
License: GPLv2 or later

---

Overview

The AI TranslatePress Translation plugin automates the translation of empty dictionary entries within your WordPress site using the OpenAI API. It processes translations in batches using WP Cron, displays real‑time logs via AJAX, and offers flexible configuration for API settings, batch size, timeout, and target translation table selection. The plugin includes robust error handling with a fallback to individual processing if batch translations return an unexpected number of results.

---

Features

• Automated Translation:
  Translates dictionary entries using OpenAI’s chat completions API.
• Batch Processing with Fallback:
  Processes records in configurable batches for efficiency. If a batch returns a mismatch in translation count, the plugin processes the affected records individually.
• Configurable Settings:
  • OpenAI API Key: Your valid API key.
  • GPT Model: Select from models like gpt-4o, gpt-4o-2024-11-20, chatgpt-4o-latest, gpt-4o-mini.
  • Translation Instructions: Set your custom prompt. Use the placeholder [originals] to insert the list of texts that need translation.
  • Batch Size: Define the number of records to process per API request (default is 10).
  • API Timeout: Set the API request timeout in seconds (default is 30).
  • Translation Table: Choose the target table for translation entries. The plugin automatically lists all tables starting with your WordPress table prefix followed by trp_dictionary_.
• Real-Time Logging:
  Detailed logs are displayed and refreshed via AJAX, showing each record’s ID, original text, and translated text.
• Process Control:
  Start and stop the translation process at any time. A visual loader and status message indicate when translations are in progress.

---

Requirements

• PHP: 7.4 or later
• WordPress: 5.0 or later
• OpenAI API Key: A valid key is required to access the translation service.

---

Installation

1. Upload the Plugin:
   • Download the plugin package.
   • Upload the entire folder to your /wp-content/plugins/ directory, or use the WordPress plugin uploader.
2. Activate the Plugin:
   • Go to Plugins > Installed Plugins in your WordPress admin.
   • Find AI TranslatePress Translation and click Activate.
3. Configure Settings:
   • Navigate to AI Translate in the WordPress admin menu.
   • Enter your OpenAI API Key.
   • Select your preferred GPT model.
   • Customize the Translation Instructions. (Remember to include the [originals] placeholder where the original texts should be inserted.)
   • Set the Batch Size and API Timeout.
   • Select the appropriate Translation Table from the provided dropdown.
   • Click Save Settings.

---

Usage

Starting the Translation Process

• Click the Translate All button on the plugin page to schedule a WP Cron event that begins batch processing of translations.
• A loader (spinner) and the note “Translation in progress…” indicate that the process is active.
• Real-time logs provide detailed information for each translation.

Stopping the Translation Process

• When a translation process is active, the Stop Translation Process button is enabled.
• Click this button to unschedule pending translation events, which stops the process.
• The plugin logs that the translation process has been stopped.

Viewing Logs

• The Translation Logs section displays timestamped messages for each step, including:
  • Batch processing status.
  • Individual record translations (formatted as:
    Record ID X translated successfully. "Original text" -> "Translated text")
• Logs are automatically refreshed via AJAX every 5 seconds.

---

How It Works

Batch Translation

1. Data Collection:
   The plugin collects a configurable number of records (as defined by the Batch Size setting) that have an empty “translated” field.
2. Prompt Construction:
   It constructs the prompt by replacing the [originals] placeholder in your Translation Instructions with a concatenated list of the original texts.
3. API Call:
   A single API request is sent to the OpenAI API using your selected GPT model and the configured API Timeout.
4. Response Handling:
   If the number of translations received matches the number of original texts, each record is updated with its translation. If not, the plugin falls back to processing the records individually.

Individual Processing Fallback

• When a batch translation returns an unexpected number of translations, the plugin processes each record one-by-one.
• Each individual API request uses the same prompt format (with [originals] replaced by the individual text).
• Successful translations are logged with both the original and translated texts.

Logging and Error Handling

• Detailed Logs:
  Every action is logged with a timestamp. Log entries include the record ID, original text, and the translation.
• Error Handling:
  The plugin automatically detects errors such as API timeouts (cURL error 28) or invalid responses, logging the error and retrying after a 30-second delay.
• AJAX Updates:
  Logs are refreshed in real time without requiring a page reload.

---

Troubleshooting

• API Timeouts or Errors:
  If you encounter repeated messages such as “cURL error 28,” consider increasing the API Timeout value in the settings.
• Mismatched Translation Count:
  Ensure that your Translation Instructions correctly include the [originals] placeholder so that the API receives the full list of texts.
• No Records Processed:
  Verify that the correct Translation Table is selected. The plugin automatically lists tables starting with your WordPress prefix and trp_dictionary_.

---

Developer Notes

• Code Structure:
  The code is organized into clear sections for settings, logging, and the translation process. Key functionalities include:
  • send_api_request(): Handles the API communication.
  • process_translation_batch(): Manages batch translation with error handling.
  • process_single_translation(): Processes individual records if batch translation fails.
• Customization:
  Developers can customize the prompt and error handling behavior as needed. The plugin follows Clear Code best practices for maintainability.

---

Conclusion

The AI TranslatePress Translation plugin provides a powerful and flexible solution for automating translations on your WordPress site using the OpenAI API. With real-time logging, configurable batch processing, and robust error handling, this plugin is designed to integrate seamlessly into your workflow and scale with your needs.

For further support, updates, or contributions, please visit Granular Concept.