readme.md

TMM.io

Translating Models

The package at https://github.com/dimsav/laravel-translatable is installed. In order to translate particular fields on an existing model, follow the steps below.

Setting up the Database and Eloquent

If you are creating a translatable model for the first time, do not add the translatable columns to the parent model's migration or model. They will be handled through the Translation Model. Hopefully the instructions here will clarify this a bit.

1. Create Translation Migration

• $table->increments('id');
• Foreign Key ID (ex. model_id) Unsigned
• Translatable Columns
• $table->string('locale')->index()
• $table->unique(['{{FOREIGN_KEY_ID_COLUMN_NAME}}', 'locale']);
• $table->foreign('{{FOREIGN_KEY_ID_COLUMN_NAME}}')->references('id')->on('{{FOREIGN_TABLE_NAME}}');

2. Create Translation Model in app/models/translation/ with namespace Models\Translation

• Extend Eloquent (or Illuminate\Database\Eloquent\Model)
• protected $table = '{{TRANSLATION_TABLE_NAME}}';
• public $timestamps = false;
• protected $fillable = [{{TRANSLATABLE_COLUMNS}}];

3. Edit Parent Model

• Use Dimsav\Translatable\Translatable trait.
• protected $translationModel = 'Models\Translation\{{TRANSLATION_MODEL_NAME}}';
• protected $translationForeignKey = '{{FOREIGN_KEY_ID_COLUMN_NAME}}';
• public $useTranslationFallback = true;
• protected $translatedAttributes = [{{TRANSLATABLE_COLUMNS}}];
• You may remove the {{TRANSLATABLE_COLUMNS}} from the Parent Model's protected $fillable; array.
• You may (and should, to avoid confusion) create a migration to remove the {{TRANSLATABLE_COLUMNS}} columns from the Parent Model's table.

How it works

The trait will use the current App::getLocale() (which can be toggled from the dropdown in the admin) when reading and saving translatable columns to and from the database. For example, if you current App::getLocale() is "en", all newly created models will be created with English translations. Furthermore, when viewing and updating any models in the admin (and viewing on the front-end) will display the English translation.

If the current App::getLocale() is "es", viewing translatable models will display the Spanish translation. However, if a Spanish translation does not exist for a particular model, it will fallback to the English translation. It should be illustrated in the admin when this occurs (see below). If the English translation does not exist (i.e. if the model was created with a Spanish translation, and no English translation has been added), and your current App::getLocale() is "de", no translation will be shown.

While editing a model in the admin, the fallback feature will be disabled (see below). Thus, if your current App::getLocale() is "es", and there is no translation for Spanish, the form field will be empty. However, the English translation will be displayed below the input in a span.text-muted (see below).

Setting up the Admin UI

A "current locale" dropdown is available in the admin that can be used to switch between the existing locales (from the locales table in the database). Adding the following UI elements will help the admin UI consistent when it comes to translated models.

1. The "Index" view for the model

• While displaying a particular translatable column, use the following code to check if a translation exists for said model.

    // Checks for an existing translation for the current locale
    @if( ! $model->hasTranslation())
      <sup>*</sup>
    @endif
  

• At the bottom of the page somewhere, add the following code snippet. This will define the asterisk defined above.

    <span class="text-muted">
      <sup>*</sup>
      No translation for {{Str::upper(App::getLocale())}} exists. Falling back to {{Str::upper(Config::get('app.fallback_locale'))}}.
    </span>
  

2. The "Edit" view for the model

• Enter the following code snippet to display the English (or otherwise configured fallback locale) version beneath any translatable column's form field. If a translation does not exist for this particular App::getLocale(), the form field will be empty.

    @if(App::getLocale() != Config::get('app.fallback_locale')
      <span class="help-block">
        English Version: {{$model->translate(Config::get('app.fallback_locale'))->[FIELD]}}
      </span>
    @endif
  

3. The "View" view for the model

• Similar to the "Index" view, we want to indicate the presence of missing translations. Next to any translatable columns, add the following code.

    @if( ! $model->hasTranslation())
      <sup>*</sup>
    @endif
  

• At the bottom of the page somewhere, add the following code snippet. This will define the asterisk defined above.

    <span class="text-muted">
      <sup>*</sup> No translation for {{Str::upper(App::getLocale())}} exists. Falling back to {{Str::upper(Config::get('app.fallback_locale'))}}.
    </span>