README

Base module for AI-powered translations in Magento 2.

Overview

This module provides a generic, extensible framework for integrating AI translation services into Magento 2. It defines the interfaces and infrastructure needed to support multiple AI providers.

Architecture

Components

1. TranslatorInterface (Api/TranslatorInterface.php)

   • Contract that all AI providers must implement
   • Methods: translate(), getCode(), getName(), isAvailable(), validateConfiguration()

2. TranslatorPool (Model/TranslatorPool.php)

   • Manages all registered translation providers
   • Provides access to active translator from configuration
   • Returns list of available providers

3. TranslationException (Exception/TranslationException.php)

   • Custom exception for translation errors

4. Configuration

   • System configuration to select active provider
   • Located in: Stores > Configuration > Orangecat > AI Translation

Creating a Translation Provider

To add a new AI provider, create a separate module that:

1. Depends on this module in module.xml:

<module name="Your_TranslatorModule">
    <sequence>
        <module name="Orangecat_TranslateAi"/>
    </sequence>
</module>

1. Implements TranslatorInterface:

namespace Your\Module\Model;

use Orangecat\TranslateAi\Api\TranslatorInterface;

class Translator implements TranslatorInterface
{
    public function translate(string $text, string $sourceLocale, string $targetLocale): string
    {
        // Your translation logic here
    }
    
    public function getCode(): string
    {
        return 'your_code'; // e.g., 'openai', 'deepseek'
    }
    
    public function getName(): string
    {
        return 'Your Provider Name';
    }
    
    public function isAvailable(): bool
    {
        // Check if properly configured (e.g., API key exists)
    }
    
    public function validateConfiguration(): array
    {
        // Return array of error messages or empty array if valid
    }
}

1. Registers in di.xml:

<type name="Orangecat\TranslateAi\Model\TranslatorPool">
    <arguments>
        <argument name="translators" xsi:type="array">
            <item name="your_code" xsi:type="object">Your\Module\Model\Translator</item>
        </argument>
    </arguments>
</type>

Usage

// Get active translator from configuration
$translator = $this->translatorPool->getActiveTranslator();

// Translate text
$translatedText = $translator->translate(
    'Hello World',
    'en_US',
    'es_ES'
);

Configuration

Navigate to: Stores > Configuration > Orangecat > AI Translation

• Active Translation Provider: Select which AI service to use

Each provider module may add its own configuration section with specific settings (API keys, models, etc.).