README

Translator Bundle for Sulu

Developed by Steeven THOMAS

SuluTranslatorBundle integrates DeepL automatic translation into the Sulu CMS 3.x admin interface. Translate your page and article content with a single click, directly from the edit form.

📂 Requirements

• PHP ^8.2
• Sulu ^3.0
• A DeepL API key (Free or Pro)

🛠️ Features

• Per-field translation button on text_line, text_area and text_editor fields
• Bulk "Translate all" button in the form toolbar to translate every text field at once
• Auto-detection of the source language by DeepL
• Target language automatically set to the locale selected in the admin dropdown
• Undo button to revert a translation to the previous value
• HTML preservation for rich text fields (CKEditor content)
• DeepL usage statistics page in admin settings (account type, billing period, character usage)
• Permission-based access to the statistics page via Sulu role system
• Pages and articles support

🇬🇧 Available translations

• English
• French
• German

📦 Dependencies

• Deepl PHP

📝 Installation

Composer

composer require itech-world/sulu-translator-bundle

Symfony Flex

If you don't use Symfony Flex, you can add the bundle to your config/bundles.php file:

return [
    // ...
    ItechWorld\SuluTranslatorBundle\ItechWorldSuluTranslatorBundle::class => ['all' => true],
];

Configuration

Step 1: Configure your DeepL API key

Add your DeepL API key to your .env or .env.local file:

DEEPL_API_KEY=your_deepl_api_key_here

Step 2: Create the bundle configuration

Create the file config/packages/itech_world_sulu_translator.yaml:

itech_world_sulu_translator:
    deepl_api_key: "%env(DEEPL_API_KEY)%"
    locale_mapping:
        en: "en-GB"
        fr: "fr"
        de: "de"

Note: The locale_mapping is optional. It maps Sulu locale codes to DeepL language codes. If a locale is not mapped, it will be converted to uppercase automatically (e.g. fr becomes FR). See DeepL supported languages for valid codes.

Step 3: Register the admin JavaScript

Edit the assets/admin/app.js to add the bundle in imports:

import 'sulu-itech-world-sulu-translator-bundle';

Step 4: BACK & Build admin assets

Edit the assets/admin/package.json to add the bundle to the list of bundles:

{
    "dependencies": {
        // ...
      "sulu-itech-world-sulu-translator-bundle": "file:../../vendor/itech-world/sulu-translator-bundle",
    }
}

In the assets/admin/ folder, run the following command:

npm install
npm run build

or

yarn install
yarn build

Step 5: Clear cache

php bin/adminconsole cache:clear

🔤 Per-field Translation

Once installed, a translate button (language icon) appears on every text_line, text_area and text_editor field in the page and article edit forms.

1. Select the target language in the Sulu locale dropdown (top of the page)
2. Click the translate button on any field
3. The field content is sent to DeepL and replaced with the translation
4. A green checkmark confirms the translation, and a red undo button appears next to it to revert to the original value

After translating individual fields, the green checkmark and red undo button are shown side by side:

🌍 Bulk Translation

A "Translate all" button is available in the form toolbar:

1. Select the target language in the locale dropdown
2. Click "Translate all" in the toolbar
3. Confirm the action in the dialog
4. All text fields are translated simultaneously

📊 DeepL Usage Statistics

The bundle provides a settings view accessible under Settings > DeepL Translator, showing your DeepL API usage:

• Account type badge (Free or Pro)
• Billing period dates (Pro accounts only)
• Characters used vs. plan limit with a visual progress bar (green / yellow / red)
• Refresh button and direct link to your DeepL dashboard

Permissions

Access to the statistics page is controlled by the Sulu permission system. A "translator" entry appears under Settings in the role permissions. Enable the View permission to grant access.

📋 Supported Field Types

🔌 REST API Endpoints

The bundle exposes two admin API endpoints:

POST /admin/api/translator/translate

Request body:

{
    "text": "Bonjour le monde",
    "target": "en",
    "source": "fr",
    "html": false
}

Response:

{
    "translation": "Hello world"
}

GET /admin/api/translator/usage

Response:

{
    "character_count": 42500,
    "character_limit": 500000,
    "account_type": "free",
    "start_time": null,
    "end_time": null
}

Note: start_time and end_time are only returned for Pro accounts. Free accounts will receive null for these fields.

🐛 Bug and Idea

See the open issues for a list of proposed features (and known issues).

💰 Support me

You can buy me a coffee to support me this plugin is 100% free.

Buy me a coffee

👨‍💻 Contact

📘  License

This bundle is under the MIT License.