Merge pull request #39 from chadidi/2.x-docs

README.md

@@ -1,8 +1,8 @@
-# translatable
+# Laravel Translatable
 
 It's a Laravel model columns translation manager
 
-## Current working model
+## How it works?
 
 ![Laravel Translatable current working model](/images/current_working_model.png)
 
@@ -16,7 +16,7 @@ composer require fevrok/laravel-translatable
 
 If you have Laravel 5.5 and up The package will automatically register itself.
 
-else you have to add the service provider to app/config/app.php
+else you have to add the service provider to `config/app.php`
 
 ```php
 Fevrok\Translatable\TranslatableServiceProvider::class,
@@ -28,37 +28,45 @@ publish config file and migration.
 php artisan vendor:publish --provider="Fevrok\Translatable\TranslatableServiceProvider"
 ```
 
-This is the contents of the published file:
+next migrate translations table
+
+```bash
+php artisan migrate
+```
+
+## Setup
+
+After finishing the installation you can open `config/translatable.php`:
 
 ```php
 return [
+   /**
+    * Set whether or not the translations is enbaled.
+    */
+   'enabled' => true,
 
    /**
-    * Default Locale || Root columns locale
-    * We will use this locale if config('app.locale') translation not exist
+    * Select default language
     */
    'locale' => 'en',
 
 ];
 ```
+And update your config accordingly.
 
-next migrate translations table
-
-```bash
-php artisan migrate
-```
-
-## Making a model translatable
+### Making a model translatable
 
 The required steps to make a model translatable are:
 
-- Just use the `Fevrok\Translatable\Translatable` trait.
+- use the `Fevrok\Translatable\Translatable` trait.
+- define the model translatable fields in `$translatable` property.
 
 Here's an example of a prepared model:
 
 ```php
-use Illuminate\Database\Eloquent\Model;
+
 use Fevrok\Translatable\Translatable;
+use Illuminate\Database\Eloquent\Model;
 
 class Item extends Model
 {
@@ -70,7 +78,8 @@ class Item extends Model
       * @var array
       */
     protected $translatable = [
-        'name', 'color'
+        'name',
+        'description',
     ];
 }
 ```
@@ -88,7 +97,7 @@ class CustomTranslation extends \Fevrok\Translatable\Models\Translation
 }
 ```
 
-Add `$translations_model` property and  give it your custom translations class.
+Add `$translations_model` property and  give it to the model you wanna customize,
 
 ```php
 use Illuminate\Database\Eloquent\Model;
@@ -106,7 +115,7 @@ class Item extends Model
     protected $translatable = [
         'name'
     ];
-	
+
     /**
       * The model used to get translatios.
       *
@@ -116,47 +125,107 @@ class Item extends Model
 }
 ```
 
-### Available methods
+## Usage
 
-Saving translations
+### Eager-load translations
 
 ```php
-$item = new Item;
-$data = array('en' => 'car', 'ar' => 'سيارة');
+// Loads all translations
+$posts = Post::with('translations')->get();
+
+// Loads all translations
+$posts = Post::all();
+$posts->load('translations');
 
-$item->setTranslations('name', $data); // setTranslations($attribute, array $translations, $save = false)
+// Loads all translations
+$posts = Post::withTranslations()->get();
 
-// or save one translation
-$item->setTranslation('name', 'en', 'car', true); // setTranslation($attribute, $locale, $value, $save = false)
+// Loads specific locales translations
+$posts = Post::withTranslations(['en', 'da'])->get();
 
-// or just do
-$item->name = 'car'; // note: this will save automaticaly unless it's the default locale
+// Loads specific locale translations
+$posts = Post::withTranslations('da')->get();
 
-// This will save if (current locale == default locale OR $save = false)
-$item->save();
+// Loads current locale translations
+$posts = Post::withTranslations('da')->get();
 ```
 
-Get translations
+### Get default language value
 
 ```php
-$item = new Item::first();
-// get current locale translation
-$item->city
-OR
-$item->getTranslation('city');
-
-// pass translation locales
-$item->getTranslation('city', 'ar'); // getTranslation($attribute, $language = null, $fallback = true)
-$item->getTranslationsOf('name', ['ar', 'en']); // getTranslationsOf($attribute, array $languages = null, $fallback = true)
+echo $post->title;
 ```
 
-Delete translations
+### Get translated value
 
 ```php
-$item = new Item::first();
-$item->deleteTranslations(['name', 'color'], ['ar', 'en']); // deleteTranslations(array $attributes, $locales = null)
+echo $post->getTranslatedAttribute('title', 'locale', 'fallbackLocale');
 ```
 
+If you do not define locale, the current application locale will be used. You can pass in your own locale as a string. If you do not define fallbackLocale, the current application fallback locale will be used. You can pass your own locale as a string. If you want to turn the fallback locale off, pass false. If no values are found for the model for a specific attribute, either for the locale or the fallback, it will set that attribute to null.
+
+### Translate the whole model
+
+```php
+$post = $post->translate('locale', 'fallbackLocale');
+echo $post->title;
+echo $post->body;
+
+// You can also run the `translate` method on the Eloquent collection
+// to translate all models in the collection.
+$posts = $posts->translate('locale', 'fallbackLocale');
+echo $posts[0]->title;
+```
+
+If you do not define locale, the current application locale will be used. You can pass in your own locale as a string. If you do not define fallbackLocale, the current application fallback locale will be used. You can pass in your own locale as a string. If you want to turn the fallback locale off, pass false. If no values are found for the model for a specific attribute, either for the locale or the fallback, it will set that attribute to null.
+
+### Check if model is translatable
+
+```php
+// with string
+if (Translatable::translatable(Post::class)) {
+    // it's translatable
+}
+
+// with object of Model or Collection
+if (Translatable::translatable($post)) {
+    // it's translatable
+}
+```
+
+### Set attribute translations
+
+```php
+$post = $post->translate('da');
+$post->title = 'foobar';
+$post->save();
+```
+
+This will update or create the translation for title of the post with the locale da. Please note that if a modified attribute is not translatable, then it will make the changes directly to the model itself. Meaning that it will overwrite the attribute in the language set as default.
+
+### Query translatable Models
+
+To search for a translated value, you can use the `whereTranslation` method.
+For example, to search for the slug of a post, you'd use
+
+```php
+$page = Page::whereTranslation('slug', 'my-translated-slug');
+// Is the same as
+$page = Page::whereTranslation('slug', '=', 'my-translated-slug');
+// Search only locale en, de and the default locale
+$page = Page::whereTranslation('slug', '=', 'my-translated-slug', ['en', 'de']);
+// Search only locale en and de
+$page = Page::whereTranslation('slug', '=', 'my-translated-slug', ['en', 'de'], false);
+```
+
+`whereTranslation` accepts the following parameter:
+
+* `field` the field you want to search in
+* `operator` the operator. Defaults to `=`. Also can be the value \(Same as [where](https://laravel.com/docs/queries#where-clauses)\)
+* `value` the value you want to search for
+* `locales` the locales you want to search in as an array. Leave as `null` if you want to search all locales
+* `default` also search in the default value/locale. Defaults to true.
+
 ## Maintainers
 
 <table>