mirror of
https://github.com/symfony/ai.git
synced 2026-03-23 23:42:18 +01:00
Add documentation for system prompt translation feature
Documents the new system prompt translation functionality added in PR #514, including: - Configuration options for enabling translation and setting custom domains - Usage examples and integration patterns - Advanced examples with service factories and testing approaches - Performance optimization strategies with caching 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Oskar Stark
303
system-prompt-translation-examples.md
Normal file
303
system-prompt-translation-examples.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# System Prompt Translation Examples
|
||||
|
||||
This document provides practical examples and patterns for implementing system prompt translation in your Symfony AI applications.
|
||||
|
||||
## Advanced Configuration Examples
|
||||
|
||||
### Environment-Specific Translation Settings
|
||||
|
||||
```yaml
|
||||
# config/packages/dev/ai.yaml
|
||||
ai:
|
||||
agent:
|
||||
system_prompt:
|
||||
enable_translation: false # Disable in development for faster debugging
|
||||
|
||||
# config/packages/prod/ai.yaml
|
||||
ai:
|
||||
agent:
|
||||
system_prompt:
|
||||
enable_translation: true
|
||||
translation_domain: 'ai_system_prompts'
|
||||
```
|
||||
|
||||
### Multiple Translation Domains
|
||||
|
||||
```php
|
||||
use Symfony\Component\Ai\Agent\InputProcessor\SystemPromptInputProcessor;
|
||||
|
||||
// Service definition for different domains
|
||||
$customerServiceProcessor = new SystemPromptInputProcessor(
|
||||
translator: $translator,
|
||||
enableTranslation: true,
|
||||
translationDomain: 'customer_service'
|
||||
);
|
||||
|
||||
$technicalSupportProcessor = new SystemPromptInputProcessor(
|
||||
translator: $translator,
|
||||
enableTranslation: true,
|
||||
translationDomain: 'technical_support'
|
||||
);
|
||||
```
|
||||
|
||||
## Translation File Organization
|
||||
|
||||
### Domain-Specific Translation Files
|
||||
|
||||
```yaml
|
||||
# translations/customer_service.en.yaml
|
||||
greeting: "Hello! I'm your customer service assistant."
|
||||
escalation: "I'll escalate this to a human representative."
|
||||
closing: "Thank you for contacting us. Is there anything else I can help you with?"
|
||||
|
||||
# translations/technical_support.en.yaml
|
||||
greeting: "Hi! I'm here to help you with technical issues."
|
||||
diagnostic: "Let me run some diagnostics to identify the problem."
|
||||
resolution: "Here's the solution to your technical issue."
|
||||
|
||||
# translations/sales.en.yaml
|
||||
greeting: "Welcome! I'm here to help you find the perfect product."
|
||||
recommendation: "Based on your needs, I recommend the following products."
|
||||
```
|
||||
|
||||
### Multilingual Examples
|
||||
|
||||
```yaml
|
||||
# translations/customer_service.fr.yaml
|
||||
greeting: "Bonjour ! Je suis votre assistant du service client."
|
||||
escalation: "Je vais transmettre cela à un représentant humain."
|
||||
closing: "Merci de nous avoir contactés. Puis-je vous aider avec autre chose ?"
|
||||
|
||||
# translations/customer_service.es.yaml
|
||||
greeting: "¡Hola! Soy tu asistente de atención al cliente."
|
||||
escalation: "Escalaré esto a un representante humano."
|
||||
closing: "Gracias por contactarnos. ¿Hay algo más en lo que pueda ayudarte?"
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Service-Based Agent Factory
|
||||
|
||||
```php
|
||||
use Symfony\Component\Ai\Agent\Agent;
|
||||
use Symfony\Component\Ai\Agent\Prompt\SystemPrompt;
|
||||
use Symfony\Contracts\Translation\TranslatorInterface;
|
||||
|
||||
class LocalizedAgentFactory
|
||||
{
|
||||
public function __construct(
|
||||
private PlatformInterface $platform,
|
||||
private TranslatorInterface $translator,
|
||||
private bool $enableTranslation = true,
|
||||
private string $defaultDomain = 'ai_agents'
|
||||
) {}
|
||||
|
||||
public function createCustomerServiceAgent(string $locale = null): Agent
|
||||
{
|
||||
$this->setLocale($locale);
|
||||
|
||||
return new Agent(
|
||||
platform: $this->platform,
|
||||
systemPrompt: new SystemPrompt('customer_service.main_prompt')
|
||||
);
|
||||
}
|
||||
|
||||
public function createTechnicalSupportAgent(string $locale = null): Agent
|
||||
{
|
||||
$this->setLocale($locale);
|
||||
|
||||
return new Agent(
|
||||
platform: $this->platform,
|
||||
systemPrompt: new SystemPrompt('technical_support.main_prompt')
|
||||
);
|
||||
}
|
||||
|
||||
private function setLocale(?string $locale): void
|
||||
{
|
||||
if ($locale && method_exists($this->translator, 'setLocale')) {
|
||||
$this->translator->setLocale($locale);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Controller Integration
|
||||
|
||||
```php
|
||||
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
|
||||
use Symfony\Component\HttpFoundation\Request;
|
||||
use Symfony\Component\Routing\Annotation\Route;
|
||||
|
||||
class AiChatController extends AbstractController
|
||||
{
|
||||
public function __construct(
|
||||
private LocalizedAgentFactory $agentFactory
|
||||
) {}
|
||||
|
||||
#[Route('/chat/{type}', methods: ['POST'])]
|
||||
public function chat(Request $request, string $type): JsonResponse
|
||||
{
|
||||
$locale = $request->getLocale();
|
||||
|
||||
$agent = match($type) {
|
||||
'customer-service' => $this->agentFactory->createCustomerServiceAgent($locale),
|
||||
'technical-support' => $this->agentFactory->createTechnicalSupportAgent($locale),
|
||||
default => throw new BadRequestException('Unknown agent type')
|
||||
};
|
||||
|
||||
// Use the localized agent...
|
||||
$response = $agent->chat($request->getContent());
|
||||
|
||||
return $this->json(['response' => $response]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Event-Driven Locale Switching
|
||||
|
||||
```php
|
||||
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
|
||||
use Symfony\Component\HttpKernel\Event\RequestEvent;
|
||||
use Symfony\Component\HttpKernel\KernelEvents;
|
||||
|
||||
class LocaleAwareAgentSubscriber implements EventSubscriberInterface
|
||||
{
|
||||
public function __construct(
|
||||
private LocalizedAgentFactory $agentFactory
|
||||
) {}
|
||||
|
||||
public static function getSubscribedEvents(): array
|
||||
{
|
||||
return [
|
||||
KernelEvents::REQUEST => 'onKernelRequest'
|
||||
];
|
||||
}
|
||||
|
||||
public function onKernelRequest(RequestEvent $event): void
|
||||
{
|
||||
$request = $event->getRequest();
|
||||
$locale = $request->headers->get('Accept-Language');
|
||||
|
||||
if ($locale) {
|
||||
// Update agent factory with current locale
|
||||
$this->agentFactory->setDefaultLocale($locale);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Translation Features
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```php
|
||||
use PHPUnit\Framework\TestCase;
|
||||
use Symfony\Component\Translation\Translator;
|
||||
use Symfony\Component\Translation\Loader\ArrayLoader;
|
||||
use Symfony\Component\Ai\Agent\InputProcessor\SystemPromptInputProcessor;
|
||||
|
||||
class SystemPromptTranslationTest extends TestCase
|
||||
{
|
||||
public function testSystemPromptTranslation(): void
|
||||
{
|
||||
$translator = new Translator('en');
|
||||
$translator->addLoader('array', new ArrayLoader());
|
||||
$translator->addResource('array', [
|
||||
'greeting' => 'Hello, I am your AI assistant'
|
||||
], 'en');
|
||||
$translator->addResource('array', [
|
||||
'greeting' => 'Hola, soy tu asistente de IA'
|
||||
], 'es');
|
||||
|
||||
$processor = new SystemPromptInputProcessor(
|
||||
translator: $translator,
|
||||
enableTranslation: true
|
||||
);
|
||||
|
||||
// Test English translation
|
||||
$translator->setLocale('en');
|
||||
$result = $processor->processInput('greeting');
|
||||
$this->assertEquals('Hello, I am your AI assistant', $result);
|
||||
|
||||
// Test Spanish translation
|
||||
$translator->setLocale('es');
|
||||
$result = $processor->processInput('greeting');
|
||||
$this->assertEquals('Hola, soy tu asistente de IA', $result);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```php
|
||||
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
|
||||
|
||||
class TranslatedAgentIntegrationTest extends WebTestCase
|
||||
{
|
||||
public function testAgentRespondsInCorrectLanguage(): void
|
||||
{
|
||||
$client = static::createClient();
|
||||
|
||||
// Test English response
|
||||
$client->request('POST', '/chat/customer-service', [], [], [
|
||||
'HTTP_ACCEPT_LANGUAGE' => 'en'
|
||||
], '{"message": "Hello"}');
|
||||
|
||||
$response = json_decode($client->getResponse()->getContent(), true);
|
||||
$this->assertStringContains('Hello', $response['response']);
|
||||
|
||||
// Test Spanish response
|
||||
$client->request('POST', '/chat/customer-service', [], [], [
|
||||
'HTTP_ACCEPT_LANGUAGE' => 'es'
|
||||
], '{"message": "Hola"}');
|
||||
|
||||
$response = json_decode($client->getResponse()->getContent(), true);
|
||||
$this->assertStringContains('Hola', $response['response']);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Organize translation keys hierarchically** - Use dot notation for better organization
|
||||
2. **Use consistent naming conventions** - Follow a pattern like `{agent_type}.{prompt_type}`
|
||||
3. **Test with multiple locales** - Ensure all supported languages work correctly
|
||||
4. **Fallback handling** - Always provide default English translations
|
||||
5. **Performance considerations** - Consider caching translated prompts for high-traffic applications
|
||||
6. **Content management** - Consider using translation management tools for non-technical team members
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Caching Translated Prompts
|
||||
|
||||
```php
|
||||
use Symfony\Contracts\Cache\CacheInterface;
|
||||
|
||||
class CachedSystemPromptInputProcessor extends SystemPromptInputProcessor
|
||||
{
|
||||
public function __construct(
|
||||
private CacheInterface $cache,
|
||||
TranslatorInterface $translator = null,
|
||||
bool $enableTranslation = false,
|
||||
string $translationDomain = null
|
||||
) {
|
||||
parent::__construct($translator, $enableTranslation, $translationDomain);
|
||||
}
|
||||
|
||||
public function processInput(string $prompt): string
|
||||
{
|
||||
if (!$this->enableTranslation || !$this->translator) {
|
||||
return $prompt;
|
||||
}
|
||||
|
||||
$locale = $this->translator->getLocale();
|
||||
$cacheKey = "system_prompt_{$locale}_{$prompt}_{$this->translationDomain}";
|
||||
|
||||
return $this->cache->get($cacheKey, function() use ($prompt) {
|
||||
return parent::processInput($prompt);
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This comprehensive documentation provides everything developers need to implement and use system prompt translation in their Symfony AI applications.
|
||||
144
system-prompt-translation.md
Normal file
144
system-prompt-translation.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# System Prompt Translation
|
||||
|
||||
The Symfony AI Agent component supports optional translation of system prompts, allowing you to provide localized system prompt text in different languages.
|
||||
|
||||
## Overview
|
||||
|
||||
System prompt translation enables AI agents to use system prompts in any locale by leveraging Symfony's translation system. This feature is particularly useful for applications that need to provide AI interactions in multiple languages.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Bundle Configuration
|
||||
|
||||
To enable system prompt translation in your Symfony application, configure the AI bundle:
|
||||
|
||||
```yaml
|
||||
# config/packages/ai.yaml
|
||||
ai:
|
||||
agent:
|
||||
system_prompt:
|
||||
enable_translation: true
|
||||
translation_domain: 'ai_prompts' # optional
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
- `enable_translation` (boolean): Enable or disable system prompt translation. Default: `false`
|
||||
- `translation_domain` (string, optional): Specify a custom translation domain for system prompts
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Translation
|
||||
|
||||
When translation is enabled, system prompts will automatically be translated using Symfony's translator:
|
||||
|
||||
```php
|
||||
use Symfony\Component\Ai\Agent\Agent;
|
||||
use Symfony\Component\Ai\Agent\Prompt\SystemPrompt;
|
||||
|
||||
// Create a system prompt that will be translated
|
||||
$systemPrompt = new SystemPrompt('greeting.assistant');
|
||||
|
||||
// The agent will automatically translate this prompt
|
||||
$agent = new Agent(
|
||||
platform: $platform,
|
||||
systemPrompt: $systemPrompt
|
||||
);
|
||||
```
|
||||
|
||||
### Translation Files
|
||||
|
||||
Create translation files for your system prompts:
|
||||
|
||||
```yaml
|
||||
# translations/messages.en.yaml
|
||||
greeting:
|
||||
assistant: "You are a helpful AI assistant."
|
||||
|
||||
# translations/messages.fr.yaml
|
||||
greeting:
|
||||
assistant: "Vous êtes un assistant IA utile."
|
||||
|
||||
# translations/messages.es.yaml
|
||||
greeting:
|
||||
assistant: "Eres un asistente de IA útil."
|
||||
```
|
||||
|
||||
### Custom Translation Domain
|
||||
|
||||
When using a custom translation domain:
|
||||
|
||||
```yaml
|
||||
# config/packages/ai.yaml
|
||||
ai:
|
||||
agent:
|
||||
system_prompt:
|
||||
enable_translation: true
|
||||
translation_domain: 'ai_prompts'
|
||||
```
|
||||
|
||||
```yaml
|
||||
# translations/ai_prompts.en.yaml
|
||||
customer_service: "You are a customer service representative..."
|
||||
technical_support: "You are a technical support specialist..."
|
||||
|
||||
# translations/ai_prompts.fr.yaml
|
||||
customer_service: "Vous êtes un représentant du service client..."
|
||||
technical_support: "Vous êtes un spécialiste du support technique..."
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Symfony's Translation component must be available
|
||||
- The TranslatorInterface service must be registered in your application
|
||||
- Translation files must be properly configured
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
The translation feature is completely optional and backward compatible:
|
||||
|
||||
- If translation is disabled (default), system prompts work exactly as before
|
||||
- If no translator is available, prompts are used as-is without translation
|
||||
- Existing code requires no changes to continue working
|
||||
|
||||
## Example: Multilingual Customer Service Agent
|
||||
|
||||
```php
|
||||
use Symfony\Component\Ai\Agent\Agent;
|
||||
use Symfony\Component\Ai\Agent\Prompt\SystemPrompt;
|
||||
|
||||
class CustomerServiceAgentFactory
|
||||
{
|
||||
public function __construct(
|
||||
private PlatformInterface $platform,
|
||||
private string $locale = 'en'
|
||||
) {}
|
||||
|
||||
public function createAgent(): Agent
|
||||
{
|
||||
// This prompt will be translated based on current locale
|
||||
$systemPrompt = new SystemPrompt('customer_service.greeting');
|
||||
|
||||
return new Agent(
|
||||
platform: $this->platform,
|
||||
systemPrompt: $systemPrompt
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
# translations/messages.en.yaml
|
||||
customer_service:
|
||||
greeting: "You are a friendly customer service representative. Always be helpful and professional."
|
||||
|
||||
# translations/messages.de.yaml
|
||||
customer_service:
|
||||
greeting: "Sie sind ein freundlicher Kundendienstmitarbeiter. Seien Sie immer hilfsbereit und professionell."
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Translation keys in system prompts should follow standard Symfony translation key conventions
|
||||
- Parameters can be passed to translated prompts using standard Symfony translation parameter syntax
|
||||
- The current request locale is used for translation, allowing automatic language switching based on user preferences
|
||||
Reference in New Issue
Block a user