Translationv0.1.0

Glovokai Address Translation

Automatically transliterates non-Latin shipping addresses in WooCommerce orders to ensure compatibility with shipping carriers.

Overview

Glovokai Address Translation is a WordPress/WooCommerce plugin that automatically detects and transliterates non-Latin characters in shipping addresses to ensure compatibility with shipping carriers and delivery services.

When customers place orders with addresses containing Japanese, Chinese, Korean, Arabic, Cyrillic, or other non-Latin scripts, the plugin automatically converts these addresses to Latin characters using AI-powered transliteration. This ensures that shipping carriers can process and deliver orders successfully.

Features

  • Automatic Translation: Automatically detects and transliterates non-Latin addresses when orders are created
  • Multi-Language Support: Supports 11+ character sets including Japanese, Chinese, Korean, Arabic, Cyrillic, Greek, Hebrew, Thai, Vietnamese, Hindi, and Polish
  • Manual Translation: Manually trigger translation for existing orders
  • Retry Translation: Retry failed translations or regenerate translations
  • Undo Translation: Revert order address to original
  • Admin Dashboard: View translations, stats, and manage settings
  • HPOS Compatible: Fully compatible with WooCommerce High-Performance Order Storage (HPOS)
  • Original Address Preservation: Original addresses are always preserved in order meta data
  • Cost Tracking: Track API costs and token usage in the Statistics dashboard

Installation

Step 1: Install the Plugin

  1. Download the plugin zip file
  2. Log in to your WordPress admin dashboard
  3. Navigate to Plugins → Add New
  4. Click Upload Plugin at the top of the page
  5. Choose the plugin zip file and click Install Now
  6. After installation completes, click Activate Plugin

Alternative: You can upload the plugin files directly to /wp-content/plugins/glovokai-address-translation/ via FTP.

Step 2: Verify Installation

After activation, you should see a new menu item: WooCommerce → Glovokai Address Translation

Configuration

Step 1: Get Your OpenAI API Key

  1. Visit https://platform.openai.com/api-keys
  2. Sign in or create an account
  3. Click Create new secret key
  4. Copy the API key immediately (you won't be able to view it again)
  5. Ensure your account has access to GPT-4o

Step 2: Configure Plugin Settings

  1. Navigate to WooCommerce → Glovokai Address Translation → Settings
  2. Enter your OpenAI API key in the OpenAI API Key field
  3. Configure the following options:
    • Auto-translate addresses: Enable this to automatically transliterate addresses when new orders are created
    • Add original address note: Enable this to add an order note containing the original address before transliteration
  4. Click Save Settings

Step 3: Test the Configuration

  1. Create a test order with a non-Latin address (for example, Japanese, Chinese, or Korean)
  2. If auto-translation is enabled, the address should be transliterated automatically within 10-30 seconds
  3. Check the order to verify the transliterated address appears in the shipping address fields

Usage

Automatic Transliteration (Recommended)

When Auto-translate addresses is enabled:

  1. Customer places an order with a non-Latin address
  2. The plugin automatically detects non-Latin characters in the address
  3. The address is transliterated using OpenAI's GPT-4o model
  4. The WooCommerce order shipping address is automatically updated with the transliterated version
  5. The original address is safely stored in order meta data

No manual intervention required.

Manual Transliteration

From the Translations List:

  1. Navigate to WooCommerce → Glovokai Address Translation → Transliterations
  2. Find the order you want to transliterate (use the Include orders without transliteration checkbox to show all orders)
  3. Click the Transliterate button on the order row
  4. Wait a few seconds for processing
  5. The page will refresh to show the transliterated address

From the Order Edit Page:

  1. Open any WooCommerce order (WooCommerce → Orders)
  2. Scroll down to find the Address Translation meta box in the sidebar
  3. Click the Transliterate button
  4. The address will be transliterated and the page will refresh

Retry Transliteration

If you need to regenerate a transliteration:

  1. Go to WooCommerce → Glovokai Address Translation → Transliterations
  2. Find the transliterated order
  3. Click the Retry button
  4. The transliteration will be regenerated (note: costs accumulate on retries)

Undo Transliteration

To restore the original address:

  1. Navigate to WooCommerce → Glovokai Address Translation → Transliterations
  2. Find the transliterated order
  3. Click the Undo button
  4. The original address will be restored in the WooCommerce order

Viewing Statistics

  1. Go to WooCommerce → Glovokai Address Translation → Statistics
  2. Use the Time period dropdown to filter by different time periods (7 days, 30 days, 90 days, 1 year, all time)
  3. View comprehensive statistics including:
    • Total cost
    • Translated orders count
    • Average cost per order
    • Token usage breakdown
    • Daily cost breakdown

Supported Character Sets

The plugin automatically detects and transliterates the following character sets:

Japanese

Hiragana, Katakana, Kanji

Chinese

Hanzi (Simplified & Traditional)

Korean

Hangul

Arabic

Arabic script

Cyrillic

Russian, Ukrainian, etc.

Greek

Greek alphabet

Hebrew

Hebrew script

Thai

Thai script

Vietnamese

Vietnamese diacritics

Hindi

Devanagari script

Polish

Polish-specific characters

Frequently Asked Questions

Does this plugin require an API key?

Yes, you need to obtain an OpenAI API key to use the translation service. The plugin uses OpenAI's GPT-4o model for accurate transliteration. You can get an API key from platform.openai.com.

Which character sets are supported?

The plugin supports Japanese, Chinese, Korean, Arabic, Cyrillic, Greek, Hebrew, Thai, Vietnamese, Hindi, and Polish character sets. The plugin uses regex patterns to detect these character sets automatically.

Can I translate existing orders?

Yes, you can manually translate existing orders from the order edit page or use the bulk translation feature in the admin dashboard. The plugin can process orders created before installation.

Is the original address preserved?

Yes, the original address is stored in order meta data and can be viewed in order notes if enabled in settings. You can also restore the original address using the Undo feature.

How much does it cost?

The plugin uses OpenAI's GPT-4o API. All costs are tracked in the Statistics dashboard. Typical cost per address transliteration is very low (usually less than $0.01). Costs accumulate if you retry translations.

How long does translation take?

Automatic transliteration typically completes within 10-30 seconds after order creation. Manual translations also complete within this timeframe.

Is the plugin compatible with HPOS?

Yes, the plugin is fully compatible with WooCommerce High-Performance Order Storage (HPOS). It works with both traditional and HPOS order storage systems.

What happens if translation fails?

If translation fails, an error message will be added to the order notes. You can retry the translation manually. Common causes include invalid API keys, insufficient OpenAI credits, or API rate limits.

Troubleshooting

Transliteration is not working

  • Verify your OpenAI API key is correct and has GPT-4o access
  • Check order notes for error messages
  • Ensure auto-translation is enabled in settings
  • Verify the address contains non-Latin characters

API errors

  • Ensure your OpenAI account has sufficient credits
  • Check the Statistics dashboard for cost information
  • Verify your API key has access to GPT-4o
  • Check for API rate limits or service outages

Old orders not transliterating

  • Use the manual transliteration feature from the Translations list
  • Or use the transliteration button on the order edit page
  • The plugin can process orders created before installation

Important Notes

API Costs: The plugin uses OpenAI's GPT-4o API. All costs are tracked in the Statistics dashboard. Typical cost per address transliteration is very low (usually less than $0.01).

Processing Time: Automatic transliteration typically completes within 10-30 seconds after order creation.

Original Address Preservation: Original addresses are always preserved in order meta data and can be restored using the Undo feature.

HPOS Compatibility: The plugin is fully compatible with WooCommerce High-Performance Order Storage (HPOS).

Supported Languages: The plugin supports transliteration for 11+ language scripts including Japanese, Chinese, Korean, Arabic, Cyrillic, Greek, Thai, Vietnamese, Hindi, Polish, and more.

Technical Details

How It Works

When a new order is created with a shipping address containing non-Latin characters:

  1. The plugin detects the character set using regex patterns (Japanese, Chinese, Arabic, etc.)
  2. It stores the original address in order meta data
  3. It calls OpenAI's GPT-4o API with a specialized prompt for the detected character set
  4. The address fields are transliterated field-by-field to ensure accuracy
  5. The WooCommerce order shipping address is updated with the transliterated version
  6. Translation cost and token usage are tracked and stored

System Requirements

  • WordPress 5.8 or higher
  • WooCommerce 8.0 or higher
  • PHP 7.4 or higher
  • OpenAI API key with GPT-4o access