October\Rain\Database\Traits\Translatable

Overview

Translatable trait provides per-row model translation using a single translation table. Locale is resolved via Site/SiteManager.

Usage:

use \October\Rain\Database\Traits\Translatable;

public $translatable = ['name', 'description'];

---

Protected Properties

protected string $translatableContext

translatableContext is the active locale override

protected string $translatableDefault

translatableDefault is the default locale cache

protected array $translatableAttributes

translatableAttributes stores loaded translation data keyed by locale

protected array $translatableOriginals

translatableOriginals stores original translation data for dirty checking

protected array $translatableBaseValues

translatableBaseValues stashes default-locale values when a non-default locale has been promoted into $attributes

---

Public Methods

public forgetAllTranslations()

public forgetAllTranslations($locale): void

forgetAllTranslations deletes all translation rows for a locale ("unpublish French")

public forgetTranslation()

public forgetTranslation($key, $locale): void

forgetTranslation deletes a single translation row

public forgetTranslations()

public forgetTranslations($key): void

forgetTranslations deletes all translation rows for an attribute (all locales)

public getAttributeTranslated()

public getAttributeTranslated($key, $locale = null, $useFallback = true): void

getAttributeTranslated is a deprecated alias for getTranslation.

public getLocale()

public getLocale(): void

getLocale returns the active locale (context override or site locale)

public getTranslatableAttributes()

public getTranslatableAttributes(): void

getTranslatableAttributes returns the translatable attribute names

public getTranslatableBaseValue()

public getTranslatableBaseValue($key): void

getTranslatableBaseValue returns the default-locale value for a translatable attribute. When a non-default locale is promoted, reads from the stash. When the default locale is active, reads from $attributes directly.

public getTranslatableContext()

public getTranslatableContext(): void

getTranslatableContext returns the active locale, resolved lazily from Site. Lazy resolution avoids issues during migrations/seeds when Site isn't booted.

public getTranslatableDefault()

public getTranslatableDefault(): void

getTranslatableDefault returns the default locale, resolved lazily from Site.

public getTranslatableOriginals()

public getTranslatableOriginals($locale = null): void

getTranslatableOriginals gets the original values of the translated attributes

public getTranslateAttributeModelClass()

public getTranslateAttributeModelClass(): void

getTranslateAttributeModelClass returns the model class used for translations. Resolved via the 'translate.attribute' container binding when available, falling back to the base TranslateAttribute model. Override per-model to use a custom translation table.

public getTranslateAttributeTable()

public getTranslateAttributeTable(): void

getTranslateAttributeTable returns the table name for translation storage

public getTranslateAttributes()

public getTranslateAttributes($locale): void

getTranslateAttributes is a deprecated helper returning every translatable attribute for a locale.

public getTranslateDirty()

public getTranslateDirty($locale = null): void

getTranslateDirty returns the translated attributes that have been changed since last sync

public getTranslatedLocales()

public getTranslatedLocales($key = null): void

getTranslatedLocales returns locales with translations. When a key is provided, returns locales for that specific attribute. Without a key, returns all locales that have any translation rows (record-level).

public getTranslation()

public getTranslation($key, $locale, $useFallback = true): void

getTranslation returns the translated value for an attribute and locale

public getTranslations()

public getTranslations($key): void

getTranslations returns all locale values for a single attribute

public hasTranslation()

public hasTranslation($key, $locale = null): void

hasTranslation checks if a translation row exists for one attribute

public hasTranslations()

public hasTranslations($locale = null): void

hasTranslations checks if any translation rows exist for the locale (record-level)

public initializeTranslatable()

public initializeTranslatable(): void

initializeTranslatable trait for a model

public isTranslatable()

public isTranslatable($key): void

isTranslatable is a deprecated alias for isTranslatableAttribute.

public isTranslatableAttribute()

public isTranslatableAttribute($key): void

isTranslatableAttribute checks if a specific attribute should be translated right now. Returns false when: default locale active, or attribute not in $translatable.

public isTranslatableEnabled()

public isTranslatableEnabled(): void

isTranslatableEnabled returns true to indicate the trait is active

public isTranslateDirty()

public isTranslateDirty($attribute = null, $locale = null): void

isTranslateDirty determines if the model or a given translated attribute has been modified for a locale

public lang()

public lang($locale): void

lang is a deprecated alias for setLocale.

public scopeOrderByTranslation()

public scopeOrderByTranslation($query, $key, $locale, $direction = 'asc'): void

scopeOrderByTranslation adds an order by clause for a translated attribute

public scopeTransOrderBy()

public scopeTransOrderBy($query, $key, $direction = 'asc', $locale = null): void

scopeTransOrderBy sorts by the translated value for the locale, defaulting to the active locale, falling back to the base column value when a translation is missing so untranslated records still sort against their default-locale value.

public scopeTransWhere()

public scopeTransWhere($query, $key, $value, $locale = null, $operator = '='): void

scopeTransWhere adds a where clause matching the base value or the translated value for the locale, defaulting to the active locale, since a missing translation row means the attribute inherits the default locale value.

public scopeWhereTranslation()

public scopeWhereTranslation($query, $key, $locale, $value, $operator = '='): void

scopeWhereTranslation adds a where clause for a translated attribute

public scopeWithTranslation()

public scopeWithTranslation($query, $locale = null): void

scopeWithTranslation eager loads translations for a single locale

public scopeWithTranslations()

public scopeWithTranslations($query): void

scopeWithTranslations eager loads all translations (all locales)

public setAttributeTranslated()

public setAttributeTranslated($key, $value, $locale = null): void

setAttributeTranslated is a deprecated alias for setTranslation with the old argument order.

public setLocale()

public setLocale($locale): void

setLocale overrides the locale context for this model instance

public setTranslation()

public setTranslation($key, $locale, $value): void

setTranslation sets a translated value for an attribute and locale

public setTranslations()

public setTranslations($key, $translations): void

setTranslations sets multiple locale values at once for a single attribute

public shouldTranslate()

public shouldTranslate(): void

shouldTranslate returns true when the active locale differs from the default. Returns false for single-locale installs so the trait is invisible.

public translateContext()

public translateContext($locale = null): void

translateContext is a deprecated combined getter/setter for the locale context.

Protected Methods

protected demoteTranslatableValues()

protected demoteTranslatableValues(): void

demoteTranslatableValues reads current $attributes back into the translation cache and restores base (default-locale) values for the DB write

protected loadTranslatableData()

protected loadTranslatableData($locale): void

loadTranslatableData loads translation data for a locale, using the eager-loaded relationship when available, falling back to a direct query

protected promoteTranslatableValues()

protected promoteTranslatableValues(): void

promoteTranslatableValues swaps translated values into $attributes and stashes the base (default-locale) values for later restoration. Called after fetch and when setLocale() changes context.

protected resolveTranslatableDefaultLocale()

protected resolveTranslatableDefaultLocale(): void

resolveTranslatableDefaultLocale reads the default locale from the Site facade. Override this to change how the default locale is determined.

protected resolveTranslatableLocale()

protected resolveTranslatableLocale(): void

resolveTranslatableLocale reads the current locale from the Site facade. Override this to change how the active locale is determined.

protected restoreForgottenTranslation()

protected restoreForgottenTranslation($key, $locale): void

restoreForgottenTranslation discards a deleted active override without losing edits to other attributes or locales.

protected restoreTranslatableBaseValues()

protected restoreTranslatableBaseValues(): void

restoreTranslatableBaseValues restores the stashed default-locale values back into $attributes

protected storeTranslatableBasicData()

protected storeTranslatableBasicData(): void

storeTranslatableBasicData stores translations for each known dirty locale

protected storeTranslatableData()

protected storeTranslatableData($locale): void

storeTranslatableData saves translation data for a single locale using upsert