### Composer Installation: Install AI Translator Bundle (Bash)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

Instructions for installing the Sulu AI Translator Bundle using Composer. It covers the standard installation command and manual registration for non-Flex projects. A command for local development installation is also mentioned.

```bash
# Install via Composer
composer require robole/sulu-ai-translator-bundle

# For non-Flex projects, manually register in config/bundles.php:
return [
    // ...
    Robole\SuluAITranslatorBundle\SuluAITranslatorBundle::class => ['all' => true],
];

# Local development installation

```

--------------------------------

### Install SuluAITranslatorBundle with Composer

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

This command installs the SuluAITranslatorBundle using Composer. Ensure you are in your project directory and have PHP 8.2 installed.

```bash
composer require robole/sulu-ai-translator-bundle
```

--------------------------------

### Install npm Dependencies and Build Admin UI

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

After adding the frontend dependency, install all npm dependencies and build the Sulu administration UI. This command is executed in the `assets/admin` directory.

```bash
cd assets/admin
npm install
npm run build
```

--------------------------------

### Install Bundle for Local Development

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

After configuring the local repository in `composer.json`, install the bundle using the `@dev` stability tag. This ensures you are using the local version for development.

```bash
composer require robole/sulu-ai-translator-bundle:@dev
```

--------------------------------

### Frontend JavaScript Integration (JavaScript)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

This JavaScript code integrates the bundle's functionality into the Sulu admin interface. It imports the bundle's assets and requires building the admin interface after installation. Dependencies are managed via npm.

```javascript
// assets/admin/app.js
import "sulu-ai-translator-bundle";

// package.json dependencies
{
    "dependencies": {
        "sulu-ai-translator-bundle": "file:../../vendor/robole/sulu-ai-translator-bundle/src/Resources/js"
    }
}

// Build the admin interface
// cd assets/admin && npm install && npm run build
```

--------------------------------

### Add Composer Repository for Sulu AI Translator Bundle

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

This snippet shows how to add the Sulu AI Translator Bundle as a local path repository in your composer.json file. This is essential for installing the dev version of the bundle by pointing Composer to its location on your local filesystem.

```json
{
    "repositories": [
        {
            "type": "path",
            "url": "./../sulu-ai-translator-bundle"
        }
    ]
}
```

--------------------------------

### Get Usage Statistics API Endpoint (PHP)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

This GET endpoint retrieves current DeepL account usage statistics, including the character count and limit. This is useful for monitoring API consumption. The response can be null if no usage data is available.

```php
// GET /admin/api/translate/usage
// Response example:
{
    "character_count": 45823,
    "character_limit": 500000
}

// Response when no usage data available:
null
```

--------------------------------

### AITranslatorToolbarAction Component: Bulk Translation Workflow (JavaScript)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

A toolbar action enabling bulk translation of all fields on a page, snippet, or form. It automates expanding collapsible blocks, sequential field translation with a progress indicator, and allows individual undo actions. The example illustrates the user workflow and progress tracking.

```javascript
// Automatically added to toolbar of:
// - Page edit forms (sulu_page.page_edit_form.details)
// - Snippet edit forms (sulu_snippet.edit_form.details)
// - Form edit forms (sulu_form.edit_form.details)

// User workflow:
// 1. Click "Bulk Translate" toolbar button
// 2. Confirm dialog appears
// 3. All collapsible blocks expand automatically
// 4. All fields translate sequentially with progress indicator
// 5. Progress shown as "(5/12)" in button label
// 6. Each field can still be individually undone

// Progress tracking example:
// Button label updates: "Bulk Translate" → "Bulk Translate (8/15)" → "Bulk Translate"
// Visual progress bar fills from 0% to 100% as translation completes
```

--------------------------------

### AITranslatorButton Component: Translate Field Content (JavaScript)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

A React component that adds translation buttons to input fields, textareas, and CKEditor instances. It facilitates individual field translation and restoring original content, with support for HTML content preservation. The example demonstrates an API call to trigger translation.

```javascript
// Component usage (automatically injected by the bundle)
// Provides translation button next to each translatable field
// - Click translate button: translates field content
// - Click undo button: restores original content
// - Supports HTML content with tag preservation

// Example API call made by the component:
fetch('/admin/api/translates', {
    method: 'POST',
    body: JSON.stringify({
        text: 'Original text to translate',
        source: null,
        target: 'de'
    })
})
.then(response => response.json())
.then(data => {
    // Field is updated with: data.translation
})
.catch(error => {
    console.error('Error translating item:', error);
});
```

--------------------------------

### Admin Navigation and Permissions: Security Configuration (PHP)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

Configures security contexts and permissions for the AI Translator features. It demonstrates how to grant 'View' permissions for usage statistics and programmatically check user access using the security checker. A navigation item is also added to the Settings menu.

```php
// Permission checking in controllers/services
use Sulu\Component\Security\Authorization\PermissionTypes;

// Security context constant
AITranslatorAdmin::SECURITY_CONTEXT // 'sulu.module.ai_translator'

// Grant permissions in Sulu admin:
// Settings → User Roles → Select Role → Permissions Tab
// Find "AI Translator Usage Statistics" → Check "View"

// Programmatic permission check:
if ($securityChecker->hasPermission(
    AITranslatorAdmin::SECURITY_CONTEXT,
    PermissionTypes::VIEW
)) {
    // User can access usage statistics view
    $usage = $deeplService->getUsage();
}

// Navigation item added to Settings menu (position 999)
// View route: /admin/#/translation
// View key: 'ai_translator.config'
```

--------------------------------

### Configure Local Development Repository

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

For local development, add a `repositories` entry to your `composer.json` file to point to the local path of the bundle. This allows you to test changes without publishing them.

```json
"repositories": [
        {
            "type": "path",
            "url": "./../local-path-to-bundle"
        }
    ],
```

--------------------------------

### Bundle Configuration for DeepL API and Locales (YAML)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

This YAML configuration file sets up the DeepL API key and maps Sulu's locale system to DeepL's language codes. It also allows disabling translations for specific locales by setting their mapping to null. The API key should be stored securely in the .env file.

```yaml
# config/packages/sulu_ai_translator.yaml
sulu_ai_translator:
    deepl_api_key: "%env(DEEPL_API_KEY)%"
    locale_mapping:
        en: "en-GB"      # Map Sulu 'en' locale to DeepL 'en-GB'
        de: "de"         # Map Sulu 'de' locale to DeepL 'de'
        fr: "fr"         # Map Sulu 'fr' locale to DeepL 'fr'
        es: null         # Disable translation for Spanish

# .env file
DEEPL_API_KEY="your-deepl-api-key-here-xxxx:fx"
```

--------------------------------

### Register Admin Routes for SuluAITranslatorBundle

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

Add the admin routes for the SuluAITranslatorBundle to your `routes_admin.yaml` file. This makes the bundle's administrative features accessible within the Sulu backend.

```yaml
SuluAITranslatorBundle:
    resource: "@SuluAITranslatorBundle/Resources/config/routes_admin.yml"
```

--------------------------------

### Import SuluAITranslatorBundle Frontend Code

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

Import the necessary frontend code for the SuluAITranslatorBundle into your `assets/admin/app.js` file. This enables the bundle's frontend functionalities.

```javascript
import "sulu-ai-translator-bundle";
```

--------------------------------

### Admin Route Configuration (YAML)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

This YAML file registers the necessary admin routes for the bundle. It exposes the translation and usage statistics API endpoints within the Sulu admin interface, making them accessible for frontend integration.

```yaml
# config/routes/routes_admin.yaml
SuluAITranslatorBundle:
    resource: "@SuluAITranslatorBundle/Resources/config/routes_admin.yml"

# This exposes:
# POST /admin/api/translates - Translate text
# GET /admin/api/translate/usage - Get usage statistics
```

--------------------------------

### Add SuluAITranslatorBundle Frontend Dependency

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

Reference the frontend code for the SuluAITranslatorBundle in your `assets/admin/package.json`. This step is crucial for integrating the bundle's UI elements into the Sulu administration panel.

```json
"dependencies": {
    "sulu-ai-translator-bundle": "file:../../vendor/robole/sulu-ai-translator-bundle/src/Resources/js"
}
```

--------------------------------

### Add DeepL API Key to .env File

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

Store your DeepL API Key in the `.env` file of your project. This key is used by the bundle to authenticate with the DeepL API for translation services.

```dotenv
DEEPL_API_KEY=...
```

--------------------------------

### Configure SuluAITranslatorBundle with DeepL API Key and Locale Mapping

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

Configure the SuluAITranslatorBundle in `config/packages/sulu_ai_translator.yaml`. This includes providing your DeepL API key and mapping your webspace locales to DeepL target languages.

```yaml
sulu_ai_translator:
    deepl_api_key: "%env(DEEPL_API_KEY)%"
    locale_mapping:
        en: "en-GB"
```

--------------------------------

### DeeplService Class for Translation and Usage (PHP)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

The core DeeplService class wraps the DeepL PHP client to handle text translation and retrieve usage statistics. It supports various translation options, including HTML tag handling. The service is auto-wired in controllers.

```php
use Robole\SuluAITranslatorBundle\Service\DeeplService;

// Service is auto-wired in controllers
class MyController extends AbstractController
{
    public function __construct(private DeeplService $deeplService) {}

    public function translateContent(): void
    {
        // Translate text from English to German with HTML tag handling
        $result = $this->deeplService->translateText(
            text: '<p>Welcome to <strong>our site</strong>!</p>',
            source: 'en-US',
            target: 'de',
            options: ['tag_handling' => 'html']
        );

        echo $result->text; // '<p>Willkommen auf <strong>unserer Website</strong>!</p>'

        // Check API usage
        $usage = $this->deeplService->getUsage();
        if ($usage) {
            $remaining = $usage->character_limit - $usage->character_count;
            echo "Characters remaining: {$remaining}";
        }
    }
}
```

--------------------------------

### Usage Statistics API Endpoint

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

Retrieves current DeepL account usage statistics, including character count and limit.

```APIDOC
## GET /admin/api/translate/usage

### Description
Retrieves current DeepL account usage statistics, including character count and limit for monitoring API consumption.

### Method
GET

### Endpoint
/admin/api/translate/usage

### Response
#### Success Response (200)
- **character_count** (integer) - The current number of characters translated.
- **character_limit** (integer) - The maximum character limit for the DeepL account.

#### Response Example
```json
{
    "character_count": 45823,
    "character_limit": 500000
}
```

#### Response Example (No Usage Data)
```json
null
```
```

--------------------------------

### TranslationController: Handle Translation Requests (PHP)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

A backend controller that manages translation requests and retrieves usage statistics. It includes locale mapping between Sulu and DeepL, handles empty text inputs, validates target languages, and preserves HTML tags during translation. Error handling for API requests is also implemented.

```php
namespace Robole\SuluAITranslatorBundle\Controller\Admin;

use Robole\SuluAITranslatorBundle\Service\DeeplService;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\JsonResponse;

class TranslationController extends AbstractController
{
    public function __construct(
        private DeeplService $deeplService,
        private ViewHandlerInterface $viewHandler,
        private array $localeMapping
    ) {}

    // Example request flow:
    public function postTranslateAction(Request $request): JsonResponse
    {
        // Empty text handling
        if (!$request->request->get('text')) {
            return new JsonResponse(['translation' => '']);
        }

        // Locale mapping: Sulu 'en' → DeepL 'en-GB'
        $source = $this->localeMapping[$request->request->get('source')] ?? null;
        $target = $this->localeMapping[$request->request->get('target')];

        // Target language validation
        if (!$target) {
            return new JsonResponse([
                'translation' => $request->request->get('text'),
                'error' => 'Translation failed: Target language not set'
            ]);
        }

        // Translate with HTML tag preservation
        $result = $this->deeplService->translateText(
            $request->request->get('text'),
            $source,
            $target,
            ['tag_handling' => 'html']
        );

        // API error handling
        if (!$result || !$result->text) {
            return new JsonResponse([
                'error' => 'Translation failed: DeepL API error (missing credentials?)'
            ], 400);
        }

        return new JsonResponse(['translation' => $result->text]);
    }
}
```

--------------------------------

### Register SuluAITranslatorBundle in bundles.php

Source: https://github.com/robole-dev/sulu-ai-translator-bundle/blob/main/README.md

If not using Symfony Flex, manually register the SuluAITranslatorBundle in your `config/bundles.php` file. This ensures the bundle is recognized by the Symfony application.

```php
return [
    //...
    Robole\SuluAITranslatorBundle\SuluAITranslatorBundle::class => ['all' => true],
];
```

--------------------------------

### Translation API Endpoint

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

This endpoint allows for the translation of text content from a source language to a target language using the DeepL API.

```APIDOC
## POST /admin/api/translates

### Description
Translates text content from a source language to a target language using the DeepL service.

### Method
POST

### Endpoint
/admin/api/translates

### Parameters
#### Request Body
- **text** (string) - Required - The text content to be translated.
- **source** (string) - Required - The source language code (e.g., 'en').
- **target** (string) - Required - The target language code (e.g., 'de').

### Request Example
```json
{
    "text": "<p>Hello, welcome to our website!</p>",
    "source": "en",
    "target": "de"
}
```

### Response
#### Success Response (200)
- **translation** (string) - The translated text content.

#### Response Example
```json
{
    "translation": "<p>Hallo, willkommen auf unserer Website!</p>"
}
```

#### Error Response
- **translation** (string) - The original text if translation failed.
- **error** (string) - A message describing the translation or API error.

#### Error Response Example (Missing Target)
```json
{
    "translation": "<p>Hello, welcome to our website!</p>",
    "error": "Translation failed: Target language not set"
}
```

#### Error Response Example (API Failure)
```json
{
    "error": "Translation failed: DeepL API error (missing credentials?)"
}
```
```

--------------------------------

### Translate Text API Endpoint (PHP)

Source: https://context7.com/robole-dev/sulu-ai-translator-bundle/llms.txt

This REST API endpoint facilitates text translation using the DeepL service. It accepts a JSON payload with text, source, and target languages. Responses include the translated text or an error message if the translation fails.

```php
// POST /admin/api/translates
// Request body example:
{
    "text": "<p>Hello, welcome to our website!</p>",
    "source": "en",
    "target": "de"
}

// Success response:
{
    "translation": "<p>Hallo, willkommen auf unserer Website!</p>"
}

// Error response (missing target):
{
    "translation": "<p>Hello, welcome to our website!</p>",
    "error": "Translation failed: Target language not set"
}

// Error response (API failure):
{
    "error": "Translation failed: DeepL API error (missing credentials?)"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.