What is AI Writer? 

AI Writer (ok_ai_writer) is a TYPO3 extension that brings AI-powered text generation directly into CKEditor. Editors can generate, preview, and iteratively refine SEO-optimized HTML content using Azure OpenAI or OpenAI (ChatGPT) — all without leaving the rich text editor.

The extension provides three CKEditor 5 plugins:

AI Text Generator

Opens a chat-style dialog where editors describe the content they need. The AI generates well-structured HTML that can be refined through follow-up prompts before inserting it into the editor.

AI Translate

Translates the entire editor content into a selected target language while preserving all HTML structure and formatting. Supports 7 languages.

Lorem Ipsum

Opens a dialog to select the number of paragraphs (1–20) and inserts Lorem Ipsum placeholder text — useful during development and layout prototyping.

Features 

• Conversational AI dialog — Chat-style interface with full conversation history for iterative content refinement.
• SEO-optimized output — The AI generates well-structured HTML with semantic headings (<h2> – <h4>) and paragraphs.
• Dual provider support — Works with both Azure OpenAI and OpenAI (ChatGPT) APIs. Switch between providers via extension configuration.
• Per-site configuration — Dedicated backend module (Web > AI Writer) allows administrators to configure different API credentials per TYPO3 site, with automatic fallback to global extension configuration.
• Encrypted credential storage — Per-site API keys are encrypted at rest using Sodium encryption derived from TYPO3's encryptionKey.
• Centralized or per-user credentials — API credentials can be configured server-side by an administrator (displayed blinded to editors) or per-user in the browser's localStorage when developer mode is enabled.
• Token usage tracking — Displays cumulative input/output token counts per session so editors stay aware of API consumption.
• AI translation — Translate entire editor content into 7 languages (Deutsch, English US/UK, Español, Français, Italiano, Türkçe) while preserving HTML structure.
• Dark mode support — All dialogs automatically adapt to the TYPO3 backend's dark mode setting, detecting the data-color-scheme attribute with prefers-color-scheme media query fallback.
• Localized UI — Ships with English and German translations.
• Lorem Ipsum helper — Additional CKEditor plugin for quick placeholder text insertion (1–20 paragraphs) during development.
• Backend proxy — API requests are routed through the TYPO3 backend, avoiding browser CORS restrictions.

Requirements 

Install via Composer 

composer require oliverkroener/ok-ai-writer

This pulls the extension and its dependencies into your TYPO3 project.

Install from a local path 

If you develop the extension locally (e.g. in a packages/ directory), add it as a path repository in your project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "packages/*"
        }
    ],
    "require": {
        "oliverkroener/ok-ai-writer": "@dev"
    }
}

Then run:

composer update oliverkroener/ok-ai-writer

Activate the extension 

After installing, set up and activate the extension:

vendor/bin/typo3 extension:setup
vendor/bin/typo3 database:updateschema
vendor/bin/typo3 cache:flush

Verify the installation 

After activation, confirm the extension is loaded:

vendor/bin/typo3 extension:list | grep ok_ai_writer

You should see ok_ai_writer in the output. The CKEditor plugins are now available for configuration.

Global extension configuration 

Open Admin Tools > Settings > Extension Configuration > ok_ai_writer to set the global defaults:

Per-site configuration (backend module) 

The extension provides a dedicated backend module at Web > AI Writer that allows administrators to configure different API credentials for each TYPO3 site. This is useful for multi-site setups where each site may use a different AI provider or API key.

To configure per-site credentials:

1. Navigate to Web > AI Writer in the TYPO3 backend.
2. Select a page from the page tree. The module automatically resolves the site root.
3. Fill in the configuration fields (Developer Mode, API Mode, API URL, API Key, Model).
4. Click Save.

Configuration resolution order:

1. Per-site configuration — if a record exists in tx_okaiwriter_configuration for the current site root page ID and has a non-empty apiUrl, it is used.
2. Global extension configuration — used as fallback when no per-site configuration is found.

Developer mode 

When devMode is enabled:

• Editors see a full settings panel in the AI dialog with editable fields for mode, endpoint URL, API key, and model.
• Client-entered credentials are saved in localStorage and override the server-side configuration.
• Server-configured values are shown as blinded hints below each field (e.g. http****************2001).
• If no client credentials are entered, the server-side config is used as fallback.

Step 1: Register the CKEditor plugins 

The extension ships an RTE preset at EXT:ok_ai_writer/Configuration/RTE/AiWriter.yaml that imports both plugins. You can either use it directly or import it into your own preset.

imports:
    - { resource: 'EXT:rte_ckeditor/Configuration/RTE/Default.yaml' }
    - { resource: 'EXT:ok_ai_writer/Configuration/RTE/AiWriter.yaml' }

editor:
  config:
    toolbar:
      items:
        - bold
        - italic
        # ... your other toolbar items ...
        - sourceEditing
        - loremIpsum
        - aiText
        - aiTranslate

$GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['my_preset']
    = 'EXT:site_package/Configuration/RTE/MyPreset.yaml';

RTE.default.preset = my_preset

RTE.default.preset = ok_ai_writer

Step 2: Set up your AI provider 

AI Text Generator 

The AI Text Generator lets you create and iteratively refine content through a conversational interface.

AI Translate 

The AI Translate plugin translates the entire editor content into a selected target language while preserving all HTML structure and formatting.

Lorem Ipsum 

The Lorem Ipsum plugin inserts placeholder text for layout prototyping.

1. Place the cursor where you want the text inserted.
2. Click the Lorem Ipsum toolbar button (text lines icon).
3. In the dialog, select the number of paragraphs to insert (1–20, default 3).
4. Click Insert or press Enter.

Request flow 

Browser (CKEditor Plugin)
    │
    │  User triggers AI Text or AI Translate
    │
    ▼
TYPO3 AJAX Routes
    POST /typo3/ajax/ok-ai-writer/generate    (AI Text)
    POST /typo3/ajax/ok-ai-writer/translate    (AI Translate)
    Body: { messages[], siteRootPageId }         (production mode)
    Body: { endpoint, apikey, mode,              (dev mode — optional overrides)
            model, messages[], siteRootPageId }
    │
    ▼
AiTextController
    │  resolveCredentials() via ConfigurationService:
    │    1. Per-site DB config (tx_okaiwriter_configuration)
    │    2. Global extension config (fallback)
    │  In devMode: client values override resolved config
    │  Prepends system prompt (SEO writer or translator)
    │
    │  generateAction() — text generation (max 2000 tokens)
    │  translateAction() — translation (max 4000 tokens)
    │
    ├── mode=azure ──▶  Azure OpenAI API  (api-key header)
    │
    └── mode=openai ──▶  OpenAI API  (Bearer token + model in body)
    │
    │  Returns: choices[].message.content (HTML)
    │           usage.prompt_tokens / completion_tokens
    │
    ▼
Response flows back to CKEditor
    │  AI Text: displayed in preview, added to conversation history
    │  AI Translate: replaces editor content directly
    ▼
Editor clicks "Insert into Editor" (AI Text)
    Content inserted at cursor position

Configuration resolution 

ConfigurationService.getConfiguration(siteRootPageId)
    │
    ├── siteRootPageId > 0
    │   └── AiWriterConfigurationRepository.findBySiteRootPageId()
    │       │  (tx_okaiwriter_configuration table)
    │       ├── row found with non-empty apiUrl → return per-site config
    │       └── no row or empty apiUrl → fall through
    │
    └── Global ExtensionConfiguration('ok_ai_writer')
        (ext_conf_template.txt values from settings.php)

The AddLanguageLabels middleware resolves the current site root page ID from the request context (page module id parameter or form editing edit[table][uid] parameter) and passes it to the ConfigurationService to load the correct credentials for injection into the frontend JavaScript.

System prompts 

The controller prepends a system message (identical for both providers) that instructs the AI. Each action uses a tailored prompt:

AI Text generation:

• Generate well-structured, SEO-optimized HTML content
• Use semantic headings (<h2>, <h3>, <h4>) and paragraphs
• Not include <h1> tags (the page already has one)
• Not include markdown formatting, code fences, or explanations
• Return only clean HTML

AI Translation:

• Translate the provided HTML content to the requested language
• Preserve all HTML tags, structure, attributes, and formatting exactly
• Only translate the visible text content
• Return only the translated HTML

Provider modes 

The controller supports two AI providers, selected via the mode extension configuration:

Azure OpenAI (mode = azure)

Authenticates via api-key HTTP header. The model is determined by the deployment name in the endpoint URL. No model parameter is sent in the request body.

OpenAI / ChatGPT (mode = openai)

Authenticates via Authorization: Bearer <key> header. The model parameter (e.g. gpt-4o) is included in the JSON request body.

Conversation mode 

The plugin supports two message modes:

Conversation mode (default)

The browser sends the full messages[] array (user + assistant turns). The controller prepends the system prompt and forwards the entire history to the AI API. This enables iterative refinement.

Legacy single-prompt mode

If no messages[] array is sent, the controller falls back to using a single prompt string. This mode exists for backwards compatibility.

Key files 

Classes/
├── Controller/
│   ├── AiTextController.php                  AJAX endpoint — proxies to AI API (generate + translate)
│   └── Backend/
│       └── ConfigurationController.php       Backend module — per-site config management
├── Domain/
│   └── Repository/
│       └── AiWriterConfigurationRepository.php  Per-site config DB layer (encrypted API keys)
├── Middleware/
│   └── AddLanguageLabels.php                 Injects XLIFF labels + site-aware config into backend JS
└── Service/
    ├── ConfigurationService.php              Config resolution (per-site → global fallback)
    └── EncryptionService.php                 Sodium encryption for API keys

Configuration/
├── Backend/
│   ├── AjaxRoutes.php                        Registers /ok-ai-writer/generate and /translate routes
│   └── Modules.php                           Registers Web > AI Writer backend module
├── Icons.php                                 Extension icon registration (SvgIconProvider)
├── JavaScriptModules.php                     ES module import map for CKEditor plugins
├── RequestMiddlewares.php                    Registers AddLanguageLabels middleware
├── RTE/
│   └── AiWriter.yaml                        CKEditor preset importing all three plugins
└── Services.yaml                             Symfony DI autowiring

Resources/
├── Private/
│   ├── Language/
│   │   ├── locallang.xlf                    English labels (CKEditor plugins)
│   │   ├── de.locallang.xlf                 German labels (CKEditor plugins)
│   │   ├── locallang_be_module.xlf          English labels (backend module)
│   │   └── de.locallang_be_module.xlf       German labels (backend module)
│   └── Templates/Backend/Configuration/
│       └── Edit.html                         Fluid template for backend module form
└── Public/
    ├── Icons/
    │   └── Extension.svg                    Extension icon
    └── JavaScript/
        ├── backend/
        │   └── form-dirty-check.js          Unsaved changes detection for backend module
        └── plugin/
            ├── ai-text.js                   CKEditor 5 AI Text plugin
            ├── ai-translate.js              CKEditor 5 AI Translate plugin
            └── lorem-ipsum.js               CKEditor 5 Lorem Ipsum plugin

Component details 

Localization 

The extension ships with two sets of language files:

CKEditor plugin labels:

Backend module labels:

CKEditor plugin labels are loaded into the backend via the AddLanguageLabels middleware and accessed in JavaScript through TYPO3.lang['label.key'].

To add a new translation, create a file named <language-code>.locallang.xlf (e.g. fr.locallang.xlf) following the XLIFF 1.2 format.

License 

This extension is licensed under the GNU General Public License v2.0 or later.

Author

Oliver Kroener

Email

ok@oliver-kroener.de

Website

oliver-kroener.de

Author 

Oliver Kroener — oliver-kroener.de

Oliver is a software engineer and consultant specializing in Power Automate, AI, Microsoft Azure, TYPO3, and cloud solutions.

• Website: oliver-kroener.de
• Email: ok@oliver-kroener.de

Support 

If you encounter issues or have questions about this extension:

• Bug reports & feature requests: Use the GitHub issue tracker
• Email: ok@oliver-kroener.de

Contributing 

Contributions are welcome. Please open a pull request or issue on GitHub.

License 

This extension is licensed under the GPL-2.0-or-later.