Translatable meta
Last updated:
On this page
With javaabu/translatable v3 installed, a meta field can have a value per language: a subtitle in English and in Dhivehi.
composer require javaabu/translatable:^3.0@dev
MetaFields::for(Post::class, [
TextInput::make('subtitle')->label(__('Subtitle'))->required()->translatable(),
Textarea::make('summary')->label(__('Summary'))->translatable(layout: 'stacked'),
TextInput::make('code'), // the same in every language
]);
->translatable() is always safe to call. The field is translatable when translatable is installed and enabled (translatable.enabled is on and there are active languages). Otherwise it's a plain field. The model itself doesn't need to be translatable.
Storing and reading
A translatable value is stored as one row per locale. A value that isn't translatable has the locale ''.
$post->setMeta('subtitle', ['en' => 'Malé', 'dv' => 'މާލެ']); // a locale map
$post->setMeta('subtitle', 'މާލެ', locale: 'dv'); // one locale
$post->setMeta('subtitle', 'މާލެ'); // the current locale
$post->getMeta('subtitle'); // the current locale, falling back
$post->getMeta('subtitle', locale: 'dv');
$post->getMetaTranslation('subtitle', 'dv', fallback: false); // null when there's no Dhivehi value
$post->getMetaTranslations('subtitle'); // ['en' => 'Malé', 'dv' => 'މާލެ']
$post->removeMeta('subtitle', 'dv'); // one locale
$post->removeMeta('subtitle'); // every locale
A read falls back in this order:
- the locale asked for (the current locale by default)
- the default locale (
Translatable::defaultLocale()) - the value without a locale
- any locale that has a value
The current locale is translatable's (Translatable::currentLocale()), so its locale middleware and language switcher apply.
Forms
In a meta form, a translatable field has one input per active language. Each input is named {key}_{locale} (subtitle_en, subtitle_dv), has its language's direction and lang, and Dhivehi gets the Thaana keyboard. Stencil renders them in tabs, or stacked with layout: 'stacked', in both Blade and React.
- Validation: the default language keeps the field's rules, and the others are optional (
requiredbecomesnullable). Use->translatable(require_all: true)to require every language. - Saving: the form saves each language that's submitted, and an empty input removes that language's value.
- Mass assignment:
fill(['meta' => ...])andfillMeta()take the same input names, or a locale map under the key.
In the record's own form
Nested in the record's own form (MetaFields::nested($post)), a translatable meta field gets inputs per language when the model implements stencil's ResolvesTranslatableFields. HasMeta provides isTranslatableField():
class Post extends Model implements ResolvesTranslatableFields
{
use HasMeta;
}
- What it answers:
meta.subtitlefrom the definitions, throughMetaFields::isTranslatable($post, 'subtitle'). The model's own fields (title) go to javaabu/translatable, so a translatable model keeps its own per-locale inputs. - Names:
meta[subtitle_en]andmeta[subtitle_dv], with the state pathsmeta.subtitle_enandmeta.subtitle_dv. Values are read from$post->meta['subtitle_dv'], and the validatedmetaarray saves as in a meta form. - The first language: the required input is the record's primary locale for a translatable model (
primaryLocale()), and the current locale otherwise. In aMetaForm, it's the default locale. - A form class instead: to keep the model as it is, implement
ResolvesTranslatableFieldson your form class and call$this->getRecord()->isTranslatableField($state_path).
Querying
whereMeta('subtitle', 'މާލެ')matches a value in any locale.orderByMeta('subtitle')sorts by the value in the current locale, falling back to the default locale and then to the value without a locale.
Without translatable
- When translatable is missing or off: before you install it, or with
translatable.enabledoff, a translatable field is a plain field. It has one input and stores values without a locale. - Values stored per locale stay readable: they're read in the app's locale, falling back to
app.fallback_locale, so turning translations off doesn't break reading. - Turning translatable meta off: set
Javaabu\Meta\Support\Translations::$enabled = falseto turn it off while keeping translatable installed for your models.
How it works
- The one place translatable is checked:
Javaabu\Meta\Support\Translations. Nothing else in the package references translatable's classes. - Which fields are translatable: those declared
->translatable()(stencil'sisDeclaredTranslatable()) while translatable is enabled. - What the form edits: a meta form with translatable fields edits a
Javaabu\Meta\Support\Translatable\TranslatableMetaRecordinstead of an array. It's a JSON-translatable model that's never saved, holding the default language's values as attributes and the others intranslations. That's what stencil and translatable expect, so per-locale inputs, rules and old input work as for any translatable model. - When that class loads: only when translatable is installed.