GitBook: [master] 4 pages modified

Author: Gummibeer

docs/README.md

@@ -8,14 +8,9 @@
 
 This is a Laravel package for translatable models. Its goal is to remove the complexity in retrieving and storing multilingual model instances. With this package you write less code, as the translations are being fetched/saved when you fetch/save your instance.
 
-### Tutorials
+## Quick Example
 
-* [How To Add Multilingual Support to Eloquent](https://laravel-news.com/how-to-add-multilingual-support-to-eloquent)
-* [How To Build An Efficient and SEO Friendly Multilingual Architecture For Your Laravel Application](https://mydnic.be/post/how-to-build-an-efficient-and-seo-friendly-multilingual-architecture-for-your-laravel-application)
-
-### Quick Example
-
-#### **Getting translated attributes**
+### **Getting translated attributes**
 
 ```php
 $post = Post::first();
@@ -28,7 +23,7 @@ App::setLocale('de');
 echo $post->title; // Mein erster Post
 ```
 
-#### **Saving translated attributes**
+### **Saving translated attributes**
 
 ```php
 $post = Post::first();
@@ -41,7 +36,7 @@ $post = Post::first();
 echo $post->translate('en')->title; // My cool post
 ```
 
-#### **Filling multiple translations**
+### **Filling multiple translations**
 
 ```php
 $data = [
@@ -54,3 +49,17 @@ $post = Post::create($data);
 echo $post->translate('fr')->title; // Mon premier post
 ```
 
+## Tutorials
+
+* [How To Add Multilingual Support to Eloquent](https://laravel-news.com/how-to-add-multilingual-support-to-eloquent)
+* [How To Build An Efficient and SEO Friendly Multilingual Architecture For Your Laravel Application](https://mydnic.be/post/how-to-build-an-efficient-and-seo-friendly-multilingual-architecture-for-your-laravel-application)
+
+## Add-Ons
+
+Thanks to the community a few packages have been written to make usage of Translatable easier when working with forms:
+
+* [Propaganistas/Laravel-Translatable-Bootforms](https://github.com/Propaganistas/Laravel-Translatable-Bootforms)
+* [TypiCMS/TranslatableBootForms](https://github.com/TypiCMS/TranslatableBootForms)
+
+
+

docs/SUMMARY.md

@@ -10,4 +10,5 @@
 * [Installation](usage/installation.md)
 * [Methods](usage/methods.md)
 * [Scopes](usage/scopes.md)
+* [Fallback locale](usage/fallback-locale.md)
 

docs/usage/fallback-locale.md

@@ -0,0 +1,91 @@
+# Fallback locale
+
+## App wide
+
+If you want to fallback to a default translation when a translation has not been found, enable this in the configuration using the `use_fallback` key. And to select the default locale, use the `fallback_locale` key.
+
+```php
+[
+    // ...
+    'use_fallback' => true,
+    'fallback_locale' => 'en',
+    // ...
+]
+```
+
+## per Model
+
+You can also define per-model the default for "if fallback should be used", by setting the `$useTranslationFallback`property:
+
+```php
+class Post extends Model
+{
+    public $useTranslationFallback = true;
+}
+```
+
+## for Properties
+
+Even though we try having all models nicely translated, some fields might left empty. What's the result? You end up with missing translations for those fields!
+
+The property fallback feature is here to help. When enabled, translatable will return the value of the fallback language for those empty properties.
+
+The feature is enabled by default on new installations. If your config file was setup before v7.1, make sure to add the following line to enable the feature:
+
+```php
+'use_property_fallback' => true,
+```
+
+Of course the fallback locales must be enabled to use this feature.
+
+If the property fallback is enabled in the configuration, then translatable will return the translation of the fallback locale for the fields where the translation is empty.
+
+### **customize empty translation property detection**
+
+This package is made to translate strings, but in general it's also able to translate numbers, bools or whatever you want to. By default a simple `empty()` call is used to detect if the translation value is empty or not. If you want to customize this or use different logic per property you can override `isEmptyTranslatableAttribute()` in your main model.
+
+```php
+protected function isEmptyTranslatableAttribute(string $key, $value): bool
+{
+    switch($key) {
+        case 'name':
+            return empty($value);
+        case 'price':
+            return !is_number($value);
+        default:
+            return is_null($value);
+    }
+}
+```
+
+## **Country based fallback**
+
+Since version v5.3 it is possible to use country based locales. For example, you can have the following locales:
+
+* English: `en`
+* Spanish: `es`
+* Mexican Spanish: `es-MX`
+* Colombian Spanish: `es-CO`
+
+To configuration for these locales looks like this:
+
+```php
+    'locales' => [ 
+        'en',
+        'es' => [
+            'MX',
+            'CO',
+        ],
+    ];
+```
+
+We can also configure the "glue" between the language and country. If for instance we prefer the format `es_MX` instead of `es-MX`, the configuration should look like this:
+
+```php
+'locale_separator' => '_',
+```
+
+What applies for the fallback of the locales using the `en-MX` format?
+
+Let's say our fallback locale is `en`. Now, when we try to fetch from the database the translation for the locale `es-MX`but it doesn't exist, we won't get as fallback the translation for `en`. Translatable will use as a fallback `es` \(the first part of `es-MX`\) and only if nothing is found, the translation for `en` is returned.
+

docs/usage/methods.md

@@ -89,6 +89,39 @@ $post->getTranslationsArray();
 Creates a clone and clones the translations.
 
 ```php
-$replicate = $post->replicateWithTranslations(); 
+$replicate = $post->replicateWithTranslations();
 ```
 
+## getDefaultLocale\(\)
+
+Returns the current default locale for the current model or `null` if no default locale is set.
+
+```php
+$post->getDefaultLocale(); // null
+```
+
+## setDefaultLocale\(?string $locale\)
+
+Sets the default locale for the current model.
+
+```php
+$post->setDefaultLocale('fr');
+$post->getDefaultLocale(); // 'fr'
+```
+
+## Translation Autoloading
+
+If the `toArray()` method is called it's possible to autoload all translations. To control this feature the package comes with a config value `to_array_always_loads_translations` and three static methods in the trait:
+
+### static enableAutoloadTranslations\(\)
+
+forces to load all translations
+
+### static disableAutoloadTranslations\(\)
+
+disables autoload and returns parent attributes
+
+### static defaultAutoloadTranslations\(\)
+
+does not change the default behavior logic
+