Configuration 

LLM provider setup 

The Cowriter extension uses the nr-llm extension for LLM provider configuration. Configure your preferred provider in the nr-llm backend module.

RTE configuration 

There are two ways to configure the CKEditor integration:

Option 1: Using the shipped preset 

If you don't have a custom RTE configuration, point the RTE at the preset this extension registers:

1. Go to your root page
2. Open Page Properties > Page TSconfig

3. Add this line:

   RTE.default.preset = cowriter

   Copied!

The preset is inherited by every page below, and brings all Cowriter toolbar items with it.

editor:
  config:
    importModules:
      - { module: '@netresearch/t3_cowriter/cowriter', exports: ['Cowriter'] }
    toolbar:
      items:
        - cowriter
        - cowriterVision
        - cowriterTranslate
        - cowriterTemplates
        - cowriterImage
        - cowriterInlineSuggestions

Translation languages and formality 

The Translate dropdown offers the languages of the site the edited record belongs to: every language of the site configuration, labelled with its title. Languages hidden from the frontend (enabled: false) are included, so editors can translate into a language before it goes live. When the record belongs to no site (a record on the root page, pid 0, or in a folder outside every site), the dropdown keeps its fixed list: German, English, French, Spanish, Italian, Dutch, Portuguese, Polish, Japanese and Chinese. The same list appears when none of the site's languages has a target code (for example a site whose only language is fil_PH, see below).

The target language is taken from the language's locale:

• The two-letter language code is used, the region is dropped: de_DE.UTF-8 and de_CH.UTF-8 both translate into de.
• English and Portuguese keep the region, because DeepL translates into their regional variants: en_GB gives en-GB, en_US gives en-US, pt_BR gives pt-BR, pt_PT gives pt-PT. Other regions of these languages (en_AU) give en or pt.
• Chinese gives zh. DeepL translates zh into Simplified Chinese; the language model receives only "Chinese" and chooses the script itself. The regions that write Traditional Chinese keep their region: zh_TW gives zh-TW, zh_HK gives zh-HK, zh_MO gives zh-MO; a locale with the script Hant and no region gives zh-TW, one with the script Hans gives zh. DeepL has no target for these codes, so nr-llm translates them with the language model.
• A language without a two-letter code (fil_PH) is not offered, nor is the C or POSIX locale.

languages:
  - languageId: 0
    title: English
    locale: en_US.UTF-8
    base: /
  - languageId: 1
    title: Deutsch
    locale: de_DE.UTF-8
    base: /de/
    cowriterFormality: formal

Image generation 

With Cowriter - Generate image an editor describes an image, nr-llm's OpenAI image service generates it, and the Cowriter stores it as a file and inserts it into the text. File fields such as the images of a content element get a Generate image button as well (In file fields). The feature is off until an administrator switches it on in the extension configuration (Admin Tools > Settings > Extension Configuration > t3_cowriter). A request from the editor cannot switch it on or choose the model.

Requirements and behaviour:

• The image plugin of netresearch/rte-ckeditor-image (extension key rte_ckeditor_image) must be loaded in the editor configuration, for example by importing its plugin configuration into the preset:

  imports:
    - { resource: 'EXT:rte_ckeditor_image/Configuration/RTE/Plugin.yaml' }

  Copied!

  The image is inserted as that plugin's image with its file reference (data-htmlarea-file-uid), like an image chosen in the file browser. TYPO3's CKEditor has no image plugin of its own, and the core RTE processing removes a plain <img> on save (denyTags: img in EXT:rte_ckeditor/Configuration/RTE/Processing.yaml). Without the plugin the button is shown disabled, says why, and requests nothing.

• An OpenAI API key in the nr-llm extension configuration (providers.openai.apiKeyIdentifier).
• The editor needs a folder to store the image in: the folder TYPO3 uses for the editor's uploads (user TSconfig options.defaultUploadFolder, otherwise the first default folder of a storage the editor may write to). The storage must be public. Without such a folder the request is refused before the image is generated, so nothing is paid for.
• The file is added with the editor's own file permissions and file mounts. Its name is made from the first words of the description and a random suffix, for example a-lighthouse-at-dusk-3f9c2a1b.png.
• Only the image data the model returns is stored, never a URL. It must be a PNG, JPEG or WebP image of at most 10 MB; anything else is refused.
• Each image counts against the editor's nr-llm budget. nr-llm 0.41 has prices for gpt-image-2, gpt-image-1.5, gpt-image-1-mini, gpt-image-1 and the DALL·E models, but none for the gpt-image-2.5 models. Unless their record in nr-llm's model list carries a price, their images count with cost 0 against a cost limit; request limits apply in every case.
• A generation can take one to two minutes; nr-llm waits up to 300 seconds for OpenAI. What cuts such a request off is PHP-FPM's request_terminate_timeout and the read timeouts of the web server and of proxies in front of TYPO3; allow them more than that. PHP's max_execution_time does not count the wait on Linux, because it measures only the script's own execution and not stream operations such as the request to OpenAI (PHP manual, set_time_limit(); on Windows the real time counts). A request that is cut off inserts nothing. Whether the image was stored depends on when it was cut off: after the image was generated and stored, the file is in the upload folder; before that, there is none. The editor's message says that the image may already be in the upload folder.
• The editor may close the dialog while the image is generated. The request goes on, and the image is inserted where the cursor was when the editor clicked the button, also when the text was edited in the meantime. This holds as long as the record stays open: saving and closing the record, or leaving the page, reloads the form, and the answer is no longer awaited. The image is then stored in the upload folder but not inserted; the file field control behaves the same.
• The description becomes the image's alternative text and the editor is told to check it. Extensions that react to new files, such as one that writes alternative texts on upload, also run for a generated image.

Inline suggestions 

While an editor writes in the rich text editor, the language model can propose how the text goes on. When the editor stops typing at the end of a paragraph, the proposal appears as grey text after the cursor; Tab inserts it, any other key, a click or leaving the editor discards it. The feature is off until an administrator switches it on in the extension configuration (Admin Tools > Settings > Extension Configuration > t3_cowriter). A request from the editor cannot switch it on or choose the configuration.

When a suggestion is asked for:

• Only after typing. Pasting, undo, a dialog's result or an accepted suggestion do not trigger one.
• Only when the cursor is at the end of a paragraph or heading without a selection, the editor has the focus, is not read-only and not in source mode, and no input method composition (IME) is in progress. Never in a list item or a table cell: there Tab indents the item or moves to the next cell, and a suggestion would compete with it.
• Each new key cancels the wait and aborts a running request; an answer that arrives after the text or the cursor changed is dropped.
• Each rich text field sends at most one request every five seconds. The route allows 12 per minute per backend user, across all fields and tabs, counted apart from the other Cowriter actions, so typing cannot use up their limit. After a refusal for the rate limit the field waits as long as the route says (Retry-After); after another failure it waits 30 seconds. Failures are not shown to the editor.

What is sent and returned:

• The request carries the text before the cursor as plain text: the current paragraph and the paragraphs before it, at most the last 1000 characters. The route refuses more. With a saved record it also carries the record's table and uid; the server looks up the record's site language with the editor's permissions and asks for a continuation in that language. Without one, the model keeps the language of the text.
• The model is asked for at most one sentence of plain text (at most 60 tokens, temperature 0.3, stopping at a line break). The route strips markup, entities, line breaks, control and direction characters and Markdown markers, keeps the first sentence and at most 200 characters, and puts a space in front when the text does not end in one. Only what looks like a tag is removed, so a<b stays; a sentence ends at ., !, ? or … followed by an upper-case word, and not after an abbreviation such as z. B., ca. or Dr..
• The suggestion is inserted as text, never as markup.

Costs:

• Every suggestion is a request to the language model and counts against the editor's nr-llm budget, whether the editor takes it or not. A request that is aborted because the editor typed on has already reached the server and is paid for when the provider answered. A backend user who keeps pausing can cause up to 12 requests per minute, however many fields are open; each carries up to 1000 characters of text and returns up to 60 tokens.
• When the budget refuses a suggestion, the editor stops asking until the page is reloaded. The refusal is not shown while typing; the Cowriter dialog shows the editor's usage and limits.

Accessibility:

• The grey text is hidden from screen readers. A polite live region next to the editor announces "Suggestion available, press Tab to accept" followed by the suggestion, and is cleared when the suggestion goes.
• Tab is taken over only while a suggestion is shown, and not in the first 800 milliseconds after it appeared: a Tab that soon was planned before the suggestion could be seen or heard, so it keeps its normal behaviour (moving the focus out of the editor) and discards the suggestion. A screen reader may announce the suggestion later than that; to leave the field while a suggestion is shown, press Escape, then Tab. Shift+Tab is never taken over.
• The toggle button (Cowriter - Inline suggestions) is a toggle with aria-pressed. The choice applies at once to every rich text field of the page and, through the browser's storage event, to the backend in other tabs. It is kept in the browser's local storage per backend user; where the browser does not allow local storage, suggestions are on again after reloading.

Task configuration 

The Cowriter dialog shows tasks from the nr-llm extension with category = 'content'. Default tasks (Improve, Summarize, Extend, Fix Grammar, Translate EN/DE) are seeded during installation.

Rewrite the following text in a more engaging tone, suitable for
a marketing audience. Output ONLY the rewritten text without
explanations.

{{input}}

Field suggestions 

The fields that get the Suggest values with AI button are set in the extension configuration (Admin Tools > Settings > Extension Configuration > t3_cowriter):

The list is extension configuration rather than page TSconfig because the button is added to the TCA, which is the same for the whole installation. After changing either setting, flush the caches so the TCA is rebuilt.

Saved prompts 

Editors save prompts from the Cowriter dialog (usage). The records are stored in the table tx_cowriter_prompt on the root level (page 0), one owner each; an editor can have up to 100. Only the owner sees an unshared prompt and only the owner deletes one in the dialog.

Hiding or deleting the record in the List module takes a prompt away from every editor, its owner included.

Alt text 

The Generate alt text button sends the selected image with an instruction to the vision model. The instruction is set in the extension configuration:

The Cowriter adds the language of the edited record to the instruction, for example Answer in German (Germany).. The language comes from the record's language field and the locale of that language in the site configuration, and is resolved on the server. There is no language hint when the record has not been saved yet, has no language field, belongs to no site, is set to "all languages", or when the editor may not read the record, its page or its language.

A request to the AJAX route may still send its own instruction in the prompt field; it replaces the configured one, as it did before the setting existed. The button in the editor sends none. The language hint is added in both cases.

Audience, tone and target length 

The Audience and Tone of voice selectors in the Cowriter dialog list the active nr-llm prompt snippets tagged audience and tone_of_voice. Maintain them in the nr-llm backend module, prompt snippets; the same snippets steer nr_repurpose. A selector without snippets is not shown.

The length step is relative to the input, or to a target length per content type set in page TSconfig:

tx_cowriter.targetLength {
    text = 150
    textmedia = 120
}

Rate limiting 

The Cowriter enforces a rate limit of 20 requests per minute per backend user. When the limit is exceeded, the API returns HTTP 429 with a Retry-After header.

Security considerations 

The Cowriter extension routes all LLM requests through the TYPO3 backend, ensuring that:

• API keys are never exposed to the frontend
• All requests are authenticated via TYPO3's backend session
• Error conditions are logged for debugging

Troubleshooting