README

SuluAITranslatorBundle

Sulu bundle that integrates DeepL API for bulk and single translations of content fields.

Features

• DeepLService to fetch translations and usage statistics from DeepL API
• "Usage statistics" admin view with permission
• Translation button next to input fields
• Toolbar button to bulk translate all fields on page, snippet and article edit views
• Supports Sulu 3

Installation

This bundle requires PHP 8.2 or later. Make sure to have installed Node 18 or later for building the Sulu administration UI.

1. Open a command console, enter your project directory and run:

composer require robole/sulu-ai-translator-bundle

⚠️ Sulu 2.6 users please install the v1.1 branch:

composer require robole/sulu-ai-translator-bundle:^1.1

If you're not using Symfony Flex, you'll also need to add the bundle in your config/bundles.php file:

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

1. Register the new routes by adding the following to your config/routes/sulu_admin.yaml:

sulu_ai_translator:
    resource: "@SuluAITranslatorBundle/Resources/config/routes_admin.yaml"
    prefix: /admin/api

1. Add the file config/packages/sulu_ai_translator.yaml with the following configuration:

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

Via locale_mapping you can map a locale key from your webspace to the according official DeepL target language. Use value null for languages that should not be translatable.

1. Reference the frontend code by adding the following to your assets/admin/package.json:

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

1. Import the frontend code by adding the following to your assets/admin/app.js:

import "sulu-ai-translator-bundle";

1. Install all npm dependencies and build the admin UI (see all options):

cd assets/admin
npm install
npm run build

1. Add your Deepl API Key to the .env file:

DEEPL_API_KEY="..."

1. Grant permissions in Sulu backend to access "DeepL Usage Statistics" view.

Limitations

• Currently only supports fields of type input[type="text"], textarea and <CkEditor />
• Translations are applied on the frontend, giving content creators the ability to check translation quality and undo changes
• Links to internal pages within text fields have to be updated by hand (obviously)

Local development

1. Add to repositories section of composer.json:

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

1. Install bundle:

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

1. Check the coding standards:

composer php-cs

1. Apply coding standards:

composer php-cs-fix

Troubleshooting

If a translation request returns the input text, it is very likely that the language key(s) defined in your locale_mapping bundle configuration are not supported by DeepL. This will be indicated in the response object.

Ideas for next versions

• Add Symfony Recipe for quicker installation of bundle.
• Replace document.querySelector with store-based approach for toggling blocks.
• Enable configuration of translation strictness for each language (e.g. formal, informal, etc.)
• Add a dropdown popup next to translation button for overwriting source and target language of a field

Disclaimer

This bundle uses the DeepL API to provide translation services. This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with DeepL SE or any of its subsidiaries or affiliates. The use of the DeepL API in this bundle is purely for functionality purposes and does not imply any relationship with the DeepL company.

DeepL is a registered trademark of DeepL SE.