Handling missing translations

Sometimes your model doesn't have a requested translation. Using the fallback functionality, you can decide what should happen.

To set up fallback you need to call static method on the facade Spatie\Translatable\Facades\Translatable. Typically, you would put this in a service provider of your own:

    // typically, in a service provider
        
    use Spatie\Translatable\Facades\Translatable;
    
    Translatable::fallback(
        ...
    );

If you want to have another fallback_locale than the app fallback locale (see config/app.php), you should pass it as $fallbackLocale parameter:

    use Spatie\Translatable\Facades\Translatable;

    Translatable::fallback(
        fallbackLocale: 'fr',
    );

If the fallback locale differs between models, you can define a getFallbackLocale() method on your model.

use Illuminate\Database\Eloquent\Model;
use Spatie\Translatable\HasTranslations;

class NewsItem extends Model
{
    use HasTranslations;

    public $fillable = ['name', 'fallback_locale'];

    public $translatable = ['name'];

    public function getFallbackLocale() : string
    {
        return $this->fallback_locale;
    }
}

Sometimes it is favored to return any translation if neither the translation for the preferred locale nor the fallback locale are set. To do so, just pass $fallbackAny to true:

    use Spatie\Translatable\Facades\Translatable;

    Translatable::fallback(
         fallbackAny: true,
    );

You can set up a fallback callback that is called when a translation key is missing/not found. It just lets you execute some custom code like logging something or contact a remote service for example.

You have to register some code you want to run, by passing a closure to $missingKeyCallback.

Here's an example with a closure that logs a warning with some info about the missing translation key:

use Spatie\Translatable\Facades\Translatable;
use Illuminate\Support\Facades\Log;

Translatable::fallback(missingKeyCallback: function (
   Model $model, 
   string $translationKey, 
   string $locale, 
   string $fallbackTranslation, 
   string $fallbackLocale,
) {

    // do something (ex: logging, alerting, etc)
    
    Log::warning('Some translation key is missing from an eloquent model', [
       'key' => $translationKey,
       'locale' => $locale,
       'fallback_locale' => $fallbackLocale,
       'fallback_translation' => $fallbackTranslation,
       'model_id' => $model->id,
       'model_class' => get_class($model), 
    ]);
});

If the closure returns a string, it will be used as the fallback translation:

use Spatie\Translatable\Facades\Translatable;
use App\Service\MyRemoteTranslationService;

Translatable::fallback(missingKeyCallback: function (
    Model $model, 
    string $translationKey, 
    string $locale, 
    string $fallbackTranslation, 
    string $fallbackLocale
    ) {
    
    return MyRemoteTranslationService::getAutomaticTranslation($fallbackTranslation, $fallbackLocale, $locale);
});

By default, a fallback will be used when you access a non-existent translation attribute.

You can disable fallbacks on a model with the $useFallbackLocale property.

use Illuminate\Database\Eloquent\Model;
use Spatie\Translatable\HasTranslations;

class NewsItem extends Model
{
    use HasTranslations;

    public $translatable = ['name'];
    
    protected $useFallbackLocale = false;
}