Nova Translatable Laravel Package

Getting Started

• Install the package with Composer and publish its config/migrations if the package provides them:

  composer require <vendor>/<package>
  php artisan vendor:publish --provider="<Vendor>\\<Package>\\ServiceProvider"
  php artisan migrate
  

• Look first at the package config file for supported locales and the “main” or default language setting. Confirm this matches your application’s config/app.php locale and any existing multilingual columns.
• Add the package trait to models that need translated attributes, then declare the translatable fields:

  use Vendor\Package\Traits\HasTranslations;
  
  class Article extends Model
  {
      use HasTranslations;
  
      public $translatable = ['title', 'body'];
  }
  

• First use case: create or edit a model in the main language, clear one of its translated fields, and save. In 0.2.3 this now persists correctly, so a good smoke test is:
  1. Set title for the main locale.
  2. Save the model.
  3. Set title to '' or null for the main locale and save again.
  4. Reload and verify the field is actually empty rather than retaining the old value.

Implementation Patterns

• Locale-aware reads and writes: Set the active locale before reading or writing translated attributes. In HTTP requests this is usually done with middleware that reads Accept-Language, a route parameter, or a session value.

  app()->setLocale($request->get('locale', config('app.locale')));
  $article->title = $request->input('title');
  $article->save();
  

• Form handling: Submit translations as arrays keyed by locale and assign them explicitly. Avoid relying on mass assignment for translated fields unless the package documents support for it.

  foreach ($request->input('translations', []) as $locale => $fields) {
      $article->setTranslations($locale, $fields);
  }
  $article->save();
  

• Clearing fields intentionally: With 0.2.3, empty strings and nulls for the main language are saved as empty. Treat this as the expected behavior when building admin screens: clearing a field should clear it, not silently preserve the previous value.
• Fallbacks: Use the package’s fallback behavior for display, but persist explicit empty values when an editor clears a field. Decide whether your application should fall back to another locale or show an empty value, and encode that in your accessors/API resources.
• API resources: Return both the active translation and the full translation map when needed:

  return [
      'title' => $article->title,
      'translations' => $article->translations,
  ];
  

• Bulk operations: When importing or syncing translations, update each locale explicitly and save once per model where possible. Verify main-language empty values in import tests, since this was the 0.2.3 regression area.
• Admin integration: Use a locale switcher that changes the form context, not the model identity. Save each locale’s form state independently, and include a “clear” action that submits an empty value rather than omitting the field.

Gotchas and Tips

• 0.2.3 is a patch release: The only documented change is “Fixed saving empty fields for main language.” There are no indicated breaking changes, new configuration requirements, or deprecations. Upgrading should be low risk, but add a regression test for clearing a main-language field.
• Empty string vs. null: Confirm how your database columns and the package treat '' versus null. The fix covers empty fields, but your validation and normalization rules should be consistent so an editor clearing a field does not accidentally trigger a fallback.
• Main-language fallback can mask bugs: If your read layer falls back to another locale when the main locale is empty, a successful clear may still display translated content. Test persistence directly on the model, not only through the rendered page.
• Mass assignment: Translated attributes often need guarded/fillable configuration. If clearing a field silently fails, check whether the attribute was actually assigned before save().
• Caching: If you cache translated models or API responses, clear the relevant cache after saving empty translations. A stale cache can make the 0.2.3 fix appear not to work.
• Locale configuration: Ensure the main language in the package config is the same locale used by your forms and seeders. A mismatch can make writes go to a non-main locale and bypass the fixed path.
• Testing: Add feature tests for:
  • Saving a non-empty main-language value.
  • Clearing a main-language value to ''.
  • Clearing a main-language value to null.
  • Clearing a secondary locale without affecting the main locale.
• Debugging: If an empty save still does not persist, inspect the exact attribute value before save(), the package’s translation table rows after save, and whether the model was recently changed. The patch specifically targets the main language, so verify the active locale at write time.
• Extension points: If the package exposes translation events, model observers, or custom resolvers, use them for audit logging of cleared translations rather than overriding package internals.