# AltVision Translations

This directory contains translation files for the AltVision WordPress plugin.

## Supported Languages

The plugin supports 31 languages with over 5 billion native speakers:

| Code | Language | Native Name | Speakers |
|------|----------|-------------|----------|
| ar | Arabic | العربية | 420M+ |
| bn | Bengali | বাংলা | 270M+ |
| cs | Czech | Čeština | 13M+ |
| da | Danish | Dansk | 6M+ |
| de | German | Deutsch | 135M+ |
| el | Greek | Ελληνικά | 13M+ |
| en | English | English | 1.5B+ |
| es | Spanish | Español | 560M+ |
| fi | Finnish | Suomi | 5M+ |
| fr | French | Français | 280M+ |
| he | Hebrew | עברית | 9M+ |
| hi | Hindi | हिन्दी | 600M+ |
| hu | Hungarian | Magyar | 13M+ |
| id | Indonesian | Bahasa Indonesia | 200M+ |
| it | Italian | Italiano | 85M+ |
| ja | Japanese | 日本語 | 125M+ |
| ko | Korean | 한국어 | 80M+ |
| nl | Dutch | Nederlands | 25M+ |
| no | Norwegian | Norsk | 5M+ |
| pl | Polish | Polski | 45M+ |
| pt | Portuguese | Português | 260M+ |
| ro | Romanian | Română | 24M+ |
| ru | Russian | Русский | 260M+ |
| sv | Swedish | Svenska | 13M+ |
| ta | Tamil | தமிழ் | 80M+ |
| th | Thai | ไทย | 60M+ |
| tr | Turkish | Türkçe | 90M+ |
| uk | Ukrainian | Українська | 45M+ |
| ur | Urdu | اردو | 230M+ |
| vi | Vietnamese | Tiếng Việt | 85M+ |
| zh | Chinese | 中文 | 1.3B+ |

## RTL (Right-to-Left) Languages

The plugin fully supports RTL languages with special CSS styling:
- **Arabic (ar)** - العربية
- **Hebrew (he)** - עברית
- **Urdu (ur)** - اردو

## File Structure

```
languages/
├── altvision-ai-alt-text-generator.pot    # Translation template (master)
├── altvision-ai-alt-text-generator-ar.po  # Arabic source
├── altvision-ai-alt-text-generator-ar.mo  # Arabic compiled (generated)
├── altvision-ai-alt-text-generator-ar-<hash>.json  # Arabic JS (generated)
└── ... (repeat for all 31 languages)
```

### File Types

- **`.pot`** - Portable Object Template - The master translation template with all translatable strings
- **`.po`** - Portable Object - Translation source files (human-editable)
- **`.mo`** - Machine Object - Compiled binary files for PHP (auto-generated)
- **`.json`** - JSON format - JavaScript translations for React components (auto-generated)

## Translation Workflow

### For Translators

1. **Get the template:**
   ```bash
   # The .pot file contains all translatable strings
   languages/altvision-ai-alt-text-generator.pot
   ```

2. **Create/Edit translations:**
   - Use [Poedit](https://poedit.net/) (recommended) or any PO editor
   - Open the `.po` file for your language
   - Translate the strings
   - Save the file

3. **Compile (automatic):**
   - The build process will generate `.mo` and `.json` files automatically
   - You only need to edit the `.po` files

### For Developers

1. **Extract strings from code:**
   ```bash
   npm run i18n:pot
   ```
   This scans all PHP and JavaScript files and updates the `.pot` template.

2. **Compile translations:**
   ```bash
   npm run i18n:compile
   ```
   This converts `.po` files to `.mo` binary files.

3. **Generate JavaScript translations:**
   ```bash
   npm run i18n:json
   ```
   This creates JSON files for React components.

4. **Complete build (all steps):**
   ```bash
   npm run i18n:build
   ```

## Tools Required

### For Translation
- **Poedit** - https://poedit.net/ (Free, cross-platform)
- **Loco Translate** - WordPress plugin for in-admin translation (alternative)

### For Development
- **WP-CLI** - WordPress command-line interface
  ```bash
  # macOS
  brew install wp-cli

  # Or download directly
  curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
  chmod +x wp-cli.phar
  sudo mv wp-cli.phar /usr/local/bin/wp
  ```

- **gettext** - For compiling translations
  ```bash
  # macOS
  brew install gettext
  brew link gettext --force

  # Ubuntu/Debian
  sudo apt-get install gettext
  ```

## Testing Translations

### Change WordPress Language

1. Go to **Settings → General** in WordPress admin
2. Select **Site Language**
3. Choose your language (e.g., Arabic, Hebrew)
4. Save changes
5. Visit the AltVision plugin pages

### Test RTL Languages

For Arabic, Hebrew, or Urdu:
1. Change site language to one of these
2. Verify the layout flips to right-to-left
3. Check that all UI elements are properly aligned

## Translation Best Practices

### Do:
✅ Keep the same level of formality as the English text
✅ Preserve placeholders like `%s`, `%d` in formatted strings
✅ Maintain line breaks and formatting
✅ Use appropriate terminology for your language
✅ Test translations in the actual UI

### Don't:
❌ Translate brand names (AltVision, WordPress)
❌ Translate technical terms (alt text, metadata) unless common
❌ Remove or reorder placeholders
❌ Edit `.mo` or `.json` files directly
❌ Translate HTML tags or code

## String Contexts

Some strings may have the same English text but different meanings. These use "context" to disambiguate:

```php
// "Post" as a noun (blog post)
_x('Post', 'noun', 'altvision-ai-alt-text-generator')

// "Post" as a verb (to publish)
_x('Post', 'verb', 'altvision-ai-alt-text-generator')
```

Pay attention to the context field in your translation editor.

## Plural Forms

Different languages have different plural rules. The plugin handles this automatically:

```php
// English: 1 item / 2 items
// Arabic: 6 different plural forms!
_n('%d item', '%d items', $count, 'altvision-ai-alt-text-generator')
```

Your `.po` file header defines the plural rules for your language.

## Need Help?

- **Poedit Documentation** - https://poedit.net/trac/wiki/Doc
- **WordPress i18n** - https://developer.wordpress.org/plugins/internationalization/
- **GNU gettext** - https://www.gnu.org/software/gettext/manual/

## Contributing

To contribute translations:

1. Fork the repository
2. Edit the `.po` file for your language
3. Test your translations
4. Submit a pull request

Or contact the plugin author to receive translation files directly.

---

**Last Updated:** 2026-03-14
**Plugin Version:** 1.2.1
**Text Domain:** altvision-ai-alt-text-generator