feat: add overwrite option to model_translate helper and LocaleModel trait

This commit adds the ability to overwrite specific attributes when creating a new translation row using the `model_translate` helper and `LocaleModel` trait.

Key changes:
- `model_translate` helper: Accepts an optional `$options` array (4th argument) and passes it to `ModelTranslateJob`.
- `ModelTranslateJob`: Accepts `$options` in constructor and merges them with defaults before calling `translateTo`.
- `LocaleModel` trait: The `translateTo` method now checks for an `overwrites` key in `$options`. If present, these values are filled into the new model instance before saving.
- Added unit tests in `LocaleModelTest` to verify the new functionality.

Co-authored-by: juzaweb <47020363+juzaweb@users.noreply.github.com>

Author: google-labs-jules[bot]

helpers/helpers.php

@@ -857,7 +857,7 @@ function current_actor(?string $guard = null): Guest|Authenticatable
     );
 }
 
-function model_translate(CanBeTranslated $model, string $sourceLocale, string $targetLocale): TranslateHistory
+function model_translate(CanBeTranslated $model, string $sourceLocale, string $targetLocale, array $options = []): TranslateHistory
 {
     if ($sourceLocale === $targetLocale) {
         throw new InvalidArgumentException('Source locale and target locale must be different');
@@ -873,7 +873,7 @@ function model_translate(CanBeTranslated $model, string $sourceLocale, string $t
         ]
     );
 
-    ModelTranslateJob::dispatch($model, $sourceLocale, $targetLocale);
+    ModelTranslateJob::dispatch($model, $sourceLocale, $targetLocale, $options);
 
     return $history;
 }

src/Traits/LocaleModel.php

@@ -95,12 +95,16 @@ public function translateTo(string $locale, string $source = 'en', array $option
         }
 
         return DB::transaction(
-            function () use ($locale, $translated, $translateHistory) {
+            function () use ($locale, $translated, $translateHistory, $options) {
                 $newTranslation = $this->replicate($this->translateReplicateExcepts ?? []);
                 $translated['source_id'] = $this->id;
                 $newTranslation->fill($translated);
                 $newTranslation->setAttribute($this->getLocaleKey(), $locale);
 
+                if (isset($options['overwrites']) && is_array($options['overwrites'])) {
+                    $newTranslation->fill($options['overwrites']);
+                }
+
                 $saved = $newTranslation->save();
 
                 if ($saved && property_exists($this, 'mediaChannels')) {

src/Translations/Jobs/ModelTranslateJob.php

@@ -29,14 +29,19 @@ class ModelTranslateJob implements ShouldQueue
     public function __construct(
         protected CanBeTranslated $model,
         protected string $sourceLocale,
-        protected string $targetLocale
+        protected string $targetLocale,
+        protected array $options = []
     ) {
         $this->onQueue(config('translator.queue', 'default'));
     }
 
     public function handle(): void
     {
-        $this->model->translateTo($this->targetLocale, $this->sourceLocale, ['force' => true]);
+        $this->model->translateTo(
+            $this->targetLocale,
+            $this->sourceLocale,
+            array_merge(['force' => true], $this->options)
+        );
 
         sleep(1);
     }

tests/Unit/LocaleModelTest.php

@@ -173,6 +173,56 @@ public function test_translate_to_replicates_media_channels()
         $this->assertTrue($newPost->hasMedia('thumbnail'), 'Media was not replicated to the new translation');
         $this->assertEquals($media->id, $newPost->getFirstMedia('thumbnail')->id);
     }
+
+    public function test_model_translate_with_overwrites()
+    {
+        Queue::fake();
+
+        $post = TestPost::create(['title' => 'Hello', 'locale' => 'en']);
+
+        $options = ['overwrites' => ['content' => 'Overwritten Content']];
+        $history = model_translate($post, 'en', 'vi', $options);
+
+        $this->assertInstanceOf(TranslateHistory::class, $history);
+
+        Queue::assertPushed(ModelTranslateJob::class, function ($job) use ($options) {
+            $reflection = new \ReflectionClass($job);
+            $jobOptions = $reflection->getProperty('options')->getValue($job);
+            return $jobOptions === $options;
+        });
+    }
+
+    public function test_translate_to_with_overwrites()
+    {
+        $this->mock(Translator::class, function ($mock) {
+            $mock->shouldReceive('translate')
+                ->with('Hello', 'en', 'vi', false)
+                ->andReturn('Xin chào');
+        });
+
+        $post = TestPost::create(['title' => 'Hello', 'content' => 'Original Content', 'locale' => 'en']);
+
+        // We simulate the call without the job wrapper to test the trait logic directly
+        $result = $post->translateTo('vi', 'en', [
+            'overwrites' => [
+                'content' => 'Overwritten Content',
+            ]
+        ]);
+
+        $this->assertTrue($result);
+
+        $this->assertDatabaseHas('test_posts', [
+            'title' => 'Xin chào',
+            'content' => 'Overwritten Content',
+            'locale' => 'vi',
+        ]);
+
+        $this->assertDatabaseHas('test_posts', [
+            'title' => 'Hello',
+            'content' => 'Original Content',
+            'locale' => 'en',
+        ]);
+    }
 }
 
 class TestPost extends Model implements CanBeTranslated