dTranslate – manual
From installation to the first translated page
This manual describes the TYPO3 extension dTranslate. Setup is completed within fifteen minutes – after which you can translate pages with three clicks.
1. Install
dTranslate is installed via Composer. Then activate the extension and run the database comparison – five dedicated tables are created, and no additional database is required.
2. Configure a language model
Both settings records reside at the root level, that is, under Web → List at the top level of the page tree (page ID 0).
First create an LLM configuration: provider, model and API key. The interface address is filled in automatically when you change the provider.
For translation we recommend a strong chat model – the quality of the result depends far more on the model here than it does with a search. You do not need an embedding model.
3. Create a translation profile
The Translation profile bundles everything that should apply to a site. It has five tabs:
- General. Title, the site the profile applies to, and the LLM configuration. If you leave the site empty, the profile becomes the default for every site without its own.
- Language. Source language, form of address (formal or casual) and a free-form style hint – for example ‘technical and factual, no promotional language’ or ‘never translate “Dreistein”’.
- Glossary. Term pairs the model must adhere to.
- Scope. Which tables may be translated, and individual additional fields in the format
table.column– for example for a FlexForm field that would otherwise not be captured. - Access. Temporarily deactivate the profile.
4. Translating a page
Open Web → Translation and select the page in the page tree. Then:
- Select the profile. Pre-filled from the site.
- Tick the target languages. Only the languages of the site to which the page belongs are offered.
- Tick the records. The page itself – title, slug and SEO fields – is always included and cannot be deselected. For the content, you decide individually.
- Set the options. "Publish translated page immediately" (otherwise it remains hidden until you review it), "Skip already translated" and "Process in the background".
- Translate selection.
Without background processing, you watch the run; with it, the worker takes over and you can close the window.
5. Large runs in the background
A run is split into units – one per record and target language – and placed in a queue. It is processed via cron …
… or via the TYPO3 Scheduler using the task dTRANSLATE: Process translation queue, likewise at one-minute intervals. Either one is sufficient – do not set up both at the same time.
Under Recent runs you can see the status, progress and usage of each run; as long as it is open, you can cancel it.
Individual pages can also be translated directly from the command line:
6. Maintaining the glossary
In the Glossary tab of the profile, you create term pairs: Source term, Target term, an optional note and the target language. If the language is left empty, the entry applies to all.
The glossary is sent with every request – as a stable preamble that the model can cache. Two dozen entries therefore cost hardly anything.
Good candidates are product and brand names that should remain unchanged, established technical terms and anything for which your organisation prescribes a particular translation.
7. Retranslating
If the original has changed, select the affected records again and start the run once more. Existing translations are refreshed from the source in the process – a run never deletes anything.
If existing content should remain untouched, tick Skip already translated: only the still missing translations are then created.
When something goes wrong
- „Anthropic has no API key"
The run did not find a profile and fell back to the extension settings. This happens with records that lie outside the page structure of a site – for example news in a system folder. Explicitly select a profile when starting.
- The page record is translated, but the content is not
A run collects the content of the selected page. Subpages are not included – you translate them by selecting them individually in the page tree.
- A field stays in the source language
Body-text fields are translated automatically. Single-line input fields are deliberately left untouched, because they usually contain names, addresses or data that a model would only make worse. If you do need a particular field, add it in the profile under Scope as
table.column.- The scheduler task does not appear
After installation, the cache must be cleared once so that TYPO3 recognises the registration. Reloading the backend window is not sufficient for this.
- A translation has become unusable
Run the run for this record again without "Skip already translated" – the translation is then regenerated from the source and overwritten.
Support with setup
Tailoring the profile, Glossary and style hint to an existing project makes the biggest difference to the result. If you would like someone at your side while doing so – or wish to hand over your entire multilingual setup: get in touch with us.