Manages translations of user-facing content - products, page HTML, emails and UI labels - for the current organisation. A translation is recorded against a source object (a type, id and optional field) and can be looked up directly or by a SHA-1 hash of the source text. The active language for a request is resolved from a query parameter, a cookie, the current profile's language preference or the browser's Accept-Language header, in that order, falling back to the current website's default language. It also drives an AI-assisted editing pass that identifies translatable text within page HTML, optionally corrects spelling and grammar, wraps newly-found text for translation, and generates translations into every configured language via the configured LLM. Registered as translationService for server-side scripts, and reached from Java via C(TranslationService.class).

Group: Managers

---

Properties

---

Methods

get(Long id) · setTranslate(Translation t, String translated) · deleteLanguage(Language lang) · deleteTranslation(Translation trans) · findTypes() · getLanguages() · searchTranslations(String langCode, String sourceType, String sourceId, String sourceField) · getTranslationByObject(String langCode, String sourceType, String sourceId) · getTranslationByObject(String langCode, String sourceType, String sourceId, String sourceField) · getTranslationBySource(String langCode, String sourceText) · getTranslationByHash(String langCode, String sourceHash) · setTranslation(String langCode, String sourceText, String sourceType, String sourceId, String translation) · setTranslation(String langCode, String sourceText, String sourceType, String sourceId, String sourceField, String translation) · copyTranslations(String sourceType, String fromSourceId, String toSourceId) · existTranslation(String langCode, String sourceText, String sourceType, String sourceId, String sourceField, String translation) · calcHash(String sourceText) · getSelectedLangCode() · selectedLangCode(Profile currentUser) · translateWithDefault(String sourceType, String sourceId, String field, String defaultText) · translate(String sourceType, String sourceId, String field, String langCode) · translate(String sourceType, String sourceId, String field) · translateText(String sourceText) · generateTranslation(String targetLangCode, String sourceText) · setTranslatedText(String translated, String sourceText) · getTranslatedFileName(String name, String langCode) · setTranslation(String langCode, Translatable translatable, String field, String copy) · isTranslationAuthor() · isTranslationAuthor(Profile user, Website website) · aiEditPageContent(String html, String sourceLangCode, boolean correctSpellingGrammar, boolean wrapTranslatableSpans, boolean createTranslations)

get(Long id)

Returns: Translation

Looks up a translation by its database id.

setTranslate(Translation t, String translated)

Returns: void

Sets the translated text on an existing translation and saves the change immediately.

deleteLanguage(Language lang)

Returns: void

Deletes a language configured for the current organisation. Logs a warning and throws a runtime exception without deleting anything if the given language belongs to a different organisation.

deleteTranslation(Translation trans)

Returns: void

Deletes a single translation. Logs a warning and throws a runtime exception without deleting anything if the given translation belongs to a different organisation than the current one.

findTypes()

Returns: List<Pair<String,Long>>

Lists the distinct translation source types recorded for the current organisation, each with the number of translations of that type.

getLanguages()

Returns: List<Language>

Lists the languages configured for the current organisation.

searchTranslations(String langCode, String sourceType, String sourceId, String sourceField)

Returns: List<Translation>

Finds translations for the current organisation matching the given language, source type and source id. Any blank filter is ignored, so passing all blank values returns every translation for the organisation. The sourceField parameter is accepted but not used to filter results.

getTranslationByObject(String langCode, String sourceType, String sourceId)

Returns: String

Looks up the stored translation for a source object in a given language, matching only a translation with no field set.

getTranslationByObject(String langCode, String sourceType, String sourceId, String sourceField)

Returns: String

Looks up the stored translation for a source object in a given language. When sourceField is given it is matched against either the translation's source field name or its source hash, so a hash can be passed in place of a field name; when sourceField is null, the translation with no field set is returned.

getTranslationBySource(String langCode, String sourceText)

Returns: String

Looks up a translation for raw source text by hashing it and delegating to a hash-based lookup.

getTranslationByHash(String langCode, String sourceHash)

Returns: String

Looks up a translation by the SHA-1 hash of its source text and its language code.

setTranslation(String langCode, String sourceText, String sourceType, String sourceId, String translation)

Returns: void

Stores a translation for a source object with no field set, delegating to the field-aware overload.

setTranslation(String langCode, String sourceText, String sourceType, String sourceId, String sourceField, String translation)

Returns: void

Creates or updates the stored translation for a source object, field and language, recording the current profile as editor. If a translation already exists for the given source type, id, field and language it is updated in place; otherwise a new one is created.

copyTranslations(String sourceType, String fromSourceId, String toSourceId)

Returns: void

Copies all translations of the given source type from one source id to another. Used when duplicating an object (e.g. a group email) so its translation labels follow the copy, which has a new id.

existTranslation(String langCode, String sourceText, String sourceType, String sourceId, String sourceField, String translation)

Returns: Boolean

Checks whether a translation already exists for the given language, source type, id and field. The sourceText and translation parameters are accepted but not used by this check.

calcHash(String sourceText)

Returns: String

Computes the SHA-1 hex hash used to look up a translation by its source text.

getSelectedLangCode()

Returns: String

Resolves the language code that should be used for content shown to the current user.

selectedLangCode(Profile currentUser)

Returns: String

Resolves the language code to use for the current request, checking in order: a selectedLangCode request parameter, a selectedLangCode cookie, the given profile's language preference, the current website's default language, and finally the browser's Accept-Language header matched against the organisation's configured languages.

translateWithDefault(String sourceType, String sourceId, String field, String defaultText)

Returns: String

Translates a source object's field into the current request's language, falling back to a default when no translation exists.

translate(String sourceType, String sourceId, String field, String langCode)

Returns: String

Translates a source object's field into the given language.

translate(String sourceType, String sourceId, String field)

Returns: String

Translates a source object's field into the current request's selected language.

translateText(String sourceText)

Returns: String

Translates raw source text into the current request's selected language, looking it up by its content hash.

generateTranslation(String targetLangCode, String sourceText)

Returns: String

Machine-translates source text into the given target language using the configured translation provider.

setTranslatedText(String translated, String sourceText)

Returns: void

Stores translated text keyed by the content hash of the source text, for the current request's selected language.

getTranslatedFileName(String name, String langCode)

Returns: String

Builds a language-specific variant of a file name by inserting the language code immediately before the file extension.

setTranslation(String langCode, Translatable translatable, String field, String copy)

Returns: void

Stores a translation for a translatable object's field, using the object's source type and id.

isTranslationAuthor()

Returns: boolean

Checks whether the current profile is authorised to author (create or edit) translations on the current website.

isTranslationAuthor(Profile user, Website website)

Returns: boolean

Checks whether the given profile is authorised to author (create or edit) translations on the given website.

aiEditPageContent(String html, String sourceLangCode, boolean correctSpellingGrammar, boolean wrapTranslatableSpans, boolean createTranslations)

Returns: Map<String,Object>

Runs an AI editing pass over a page's HTML body: identifies translatable text, optionally corrects spelling and grammar, wraps translatable text in trans-lookup spans, and generates translations for every configured language other than the source language. Only leaf elements (elements with no element children) are treated as text segments, and any element inside a data-dynamic-href container or a keditor-component-data element is left untouched entirely - component structure and attributes are never modified, only text content and newly-inserted trans-lookup spans. An element already wrapped as a trans-lookup span is not re-corrected or re-wrapped on a later run - it is only used to backfill translations for languages that don't already have one, so a translator's manual edits are never overwritten. Kcode placeholder tokens are masked before sending text to the LLM and restored afterwards; a segment is skipped rather than risking corruption if a token goes missing from the AI's response.