# AI eShop Optimizer - Translation Guide

## Overview

AI eShop Optimizer (including the AI Chat addon) is fully translatable. This guide explains how to translate the plugin into your language.

## Quick Facts

- **Text Domain**: `ai-eshop-optimizer`
- **POT File**: `languages/ai-eshop-optimizer.pot`
- **Total Strings**: 545 translatable strings
- **Includes**: Main plugin + AI Chat addon
- **Existing Translations**: Greek (el) - `ai-eshop-optimizer-el.po`

## Translation Files in This Directory

```
languages/
├── ai-eshop-optimizer.pot          # Template file (English source)
├── ai-eshop-optimizer-el.po        # Greek translation (PO source)
├── ai-eshop-optimizer-el.mo        # Greek translation (compiled binary)
└── ai-eshop-optimizer-el.l10n.php  # Greek translation (PHP format for WP 6.5+)
```

## How to Translate

### Method 1: Using Poedit (Recommended)

1. **Download Poedit**: https://poedit.net/
2. **Open POT file**: File → Open → `ai-eshop-optimizer.pot`
3. **Create new translation**:
   - Click "Create New Translation"
   - Select your language (e.g., French, German, Spanish)
4. **Translate strings**:
   - Go through each English string
   - Enter translation in your language
5. **Save**:
   - File → Save As
   - Name format: `ai-eshop-optimizer-{locale}.po`
   - Examples:
     - French: `ai-eshop-optimizer-fr_FR.po`
     - German: `ai-eshop-optimizer-de_DE.po`
     - Spanish: `ai-eshop-optimizer-es_ES.po`
6. **Compile**: Poedit automatically creates `.mo` file

### Method 2: Using Loco Translate Plugin

1. **Install Loco Translate**: From WordPress.org
2. **Go to**: Loco Translate → Plugins → AI eShop Optimizer
3. **Create translation**: Choose your language
4. **Translate in browser**: Direct translation interface
5. **Save**: Automatically compiles to .mo

### Method 3: Using translate.wordpress.org

1. **Visit**: https://translate.wordpress.org/
2. **Search**: AI eShop Optimizer
3. **Select language**: Choose your locale
4. **Translate online**: Browser-based translation
5. **Approved translations** are automatically included in WordPress updates

## File Naming Convention

WordPress uses specific locale codes for translations:

| Language | Locale Code | PO File Name |
|----------|-------------|--------------|
| English | en_US | (default, no translation needed) |
| Greek | el | ai-eshop-optimizer-el.po |
| French (France) | fr_FR | ai-eshop-optimizer-fr_FR.po |
| German | de_DE | ai-eshop-optimizer-de_DE.po |
| Spanish (Spain) | es_ES | ai-eshop-optimizer-es_ES.po |
| Italian | it_IT | ai-eshop-optimizer-it_IT.po |
| Portuguese (Portugal) | pt_PT | ai-eshop-optimizer-pt_PT.po |
| Portuguese (Brazil) | pt_BR | ai-eshop-optimizer-pt_BR.po |
| Dutch | nl_NL | ai-eshop-optimizer-nl_NL.po |
| Russian | ru_RU | ai-eshop-optimizer-ru_RU.po |
| Chinese (Simplified) | zh_CN | ai-eshop-optimizer-zh_CN.po |
| Japanese | ja | ai-eshop-optimizer-ja.po |
| Korean | ko_KR | ai-eshop-optimizer-ko_KR.po |

Full list: https://make.wordpress.org/polyglots/teams/

## Translation Contexts

The plugin includes strings from:

### Main Plugin Features
- Product recommendations
- Upsell/cross-sell optimization
- Analytics dashboard
- Settings pages
- Admin notifications

### AI Chat Addon Features
- Chat interface (frontend)
- Training page (admin)
- Embedding management
- Settings and configuration
- Error messages and tooltips

## Important Notes

### Placeholders

Some strings contain placeholders that should NOT be translated:

```php
// Example with %s placeholder
__('Welcome, %s!', 'ai-eshop-optimizer')

// Translation should keep %s:
"Καλώς ήρθες, %s!"  // Greek
"Bienvenue, %s!"    // French
```

### HTML in Strings

Some strings may contain HTML tags. Keep the HTML structure:

```php
// Example with HTML
__('Click <strong>here</strong> to continue', 'ai-eshop-optimizer')

// Keep <strong> tags in translation:
"Κάντε κλικ <strong>εδώ</strong> για να συνεχίσετε"  // Greek
```

### Emojis

Emojis are used throughout the interface. Keep them or adapt to your culture:

```php
__('🤖 AI Chat', 'ai-eshop-optimizer')  // Robot emoji is universal
__('✓ Success!', 'ai-eshop-optimizer')  // Checkmark is universal
```

## Testing Your Translation

1. **Place files**: Copy `.mo` file to `/wp-content/plugins/ai-eshop-optimizer/languages/`
2. **Set language**: WordPress Settings → General → Site Language
3. **Check**: Visit plugin pages to see translations
4. **Test all areas**:
   - Admin menu items
   - Settings pages
   - AI Chat interface
   - Training modal
   - Error messages

## Updating Translations

When the plugin is updated with new strings:

1. **Get new POT**: Download latest `ai-eshop-optimizer.pot`
2. **Update PO**: Poedit → Catalog → Update from POT file
3. **Translate new**: Only new strings need translation
4. **Save**: Creates updated .mo file

### ⚠️ 66 entries are NOT in the .pot and must not be deleted

`ai-eshop-optimizer-runtime` is a **separate plugin that shares this text
domain** and has no `languages/` directory of its own, so its Greek lives in
*this* catalogue. But the `.pot` is generated by scanning only this plugin's
directory (`build/i18n.mjs` runs `wp i18n make-pot .`), so the runtime's
own strings never appear in it.

The consequence to know about: **66 live entries look stale to any
`.pot`-vs-`.po` comparison, and to "Purge deleted translations" in Poedit.**
They are recognisable by their references, which cross into the other plugin:

```
#: ../ai-eshop-optimizer-runtime/assets/email-templates/magic-link.php:41
```

Among them are the magic-link sign-in emails, the account-notification
settings and the repeat-order strings. Deleting them does not fail loudly; the
emails simply go out in English.

**Rule: an entry whose reference starts with `../` is live. Keep it.**

A durable fix would be to merge a runtime template into this one at build time
(`wp i18n make-pot` accepts `--merge=<paths>`), so the runtime's strings become
visible to translators instead of only being translatable by hand. That has not
been done, because it changes what the wp.org template advertises for a plugin
those strings do not ship in, and that is a product call rather than a build
detail.

## Contributing Your Translation

To share your translation with the community:

### Option 1: WordPress.org
Upload to https://translate.wordpress.org/ (recommended)

### Option 2: GitHub
Submit a pull request with your `.po` and `.mo` files

### Option 3: Email
Send translations to plugin author

## Regenerating POT File

If you modify the plugin and need to extract new strings:

```bash
# Method 1: Using WP-CLI (if installed)
wp i18n make-pot . languages/ai-eshop-optimizer.pot --domain=ai-eshop-optimizer

# Method 2: Using provided PHP script
php generate-pot-chat.php
```

The script `generate-pot-chat.php` is included in the plugin root directory.

## Translation Statistics

Current POT file (generated 2025-01-27):
- **Main Plugin**: ~382 strings
- **AI Chat Addon**: ~163 strings
- **Total**: 545 strings
- **File Size**: ~76 KB

## Support

Need help with translations?

- **Documentation**: https://developer.wordpress.org/plugins/internationalization/
- **Poedit Guide**: https://poedit.net/trac/wiki/Doc
- **WordPress Polyglots**: https://make.wordpress.org/polyglots/

## License

Translations follow the same GPL3 license as the plugin.

---

**Thank you for helping make AI eShop Optimizer accessible to more users worldwide!** 🌍

## Hebrew (he_IL) and Arabic (ar): storefront subset, 21 Oct 2026

The two catalogues cover the strings a visitor sees (the storefront subset: cards, cart, consent,
wishlist, ratings, swatches, checkout fields, newsletter, waitlist, withdrawal flow and emails, sign-in
links, cookie descriptions), about 620 of the 18,000 entries. Admin screens stay English. Both are
generated from `ai-eshop-optimizer.pot` and edited like any other `.po`; `npm run build` compiles them
and writes the Runtime's subset (`build/i18n-runtime.mjs`). RTL layout needs no catalogue: the storefront
sheets use logical properties and mirror under `[dir="rtl"]`.