Skip to content
This repository has been archived by the owner on Jun 18, 2019. It is now read-only.

Commit

Permalink
Update readme.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@dimsav
dimsav committed May 6, 2015
1 parent e3ee637 commit 23b7ea8
Showing 1 changed file with 97 additions and 59 deletions.
156 changes: 97 additions & 59 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ If you want to store translations of your models into the database, this package
* [Demo](#what-is-this-package-doing)
* [Installation](#installation-in-4-steps)
* [Configuration](#configuration)
* [Documentation](#documentation)
* [Support](#faq)

## Laravel compatibility
Expand All @@ -29,33 +30,33 @@ If you want to store translations of your models into the database, this package

## Demo

Getting translated attributes
**Getting translated attributes**

```php
$country = Country::where('code', '=', 'gr')->first();
echo $country->translate('en')->name; // Greece
$greece = Country::where('code', 'gr')->first();
echo $greece->translate('en')->name; // Greece

App::setLocale('en');
echo $country->name; // Greece
echo $greece->name; // Greece

App::setLocale('de');
echo $country->name; // Griechenland
echo $greece->name; // Griechenland
```

Saving translated attributes
**Saving translated attributes**

```php
$country = Country::where('code', '=', 'gr')->first();
echo $country->translate('en')->name; // Greece
$greece = Country::where('code', 'gr')->first();
echo $greece->translate('en')->name; // Greece

$country->translate('en')->name = 'abc';
$country->save();
$greece->translate('en')->name = 'abc';
$greece->save();

$country = Country::where('code', '=', 'gr')->first();
echo $country->translate('en')->name; // abc
$greece = Country::where('code', 'gr')->first();
echo $greece->translate('en')->name; // abc
```

Filling multiple translations
**Filling multiple translations**

```php
$data = array(
Expand All @@ -64,9 +65,9 @@ Filling multiple translations
'fr' => array('name' => 'Grèce'),
);

$country = Country::create($data);
$greece = Country::create($data);

echo $country->translate('fr')->name; // Grèce
echo $greece->translate('fr')->name; // Grèce
```

## Installation in 4 steps
Expand Down Expand Up @@ -180,6 +181,87 @@ class Country extends Eloquent

```

## Documentation

**Please read the installation steps first, to understand what classes need to be created.**

### Available methods

```php
// This is how we determine the current locale.
// It is set by laravel or other packages.
App::getLocale(); // 'fr'

// To use this package, first we need an instance of our model
$germany = Country::where('code', 'de')->first();

// This returns an instance of CountryTranslation of using the current locale.
// So in this case, french. If no french translation is found, it returns null.
$translation = $germany->translate();

// If an german translation exists, it returns an instance of
// CountryTranslation. Otherwise it returns null.
$translation = $germany->translate('de');

// If a german translation doesn't exist, it attempts to get a translation
// of the fallback language (see fallback locale section below).
$translation = $germany->translate('de', true);

// Alias of the above.
$translation = $germany->translateOrDefault('de');

// Returns instance of CountryTranslation of using the current locale.
// If no translation is found, it returns a fallback translation
// if enabled in the configuration.
$translation = $germany->getTranslation();

// If an german translation exists, it returns an instance of
// CountryTranslation. Otherwise it returns null.
// Same as $germany->translate('de');
$translation = $germany->getTranslation('de', true);

// Returns true/false if the model has translation about the current locale.
$germany->hasTranslation();

// Returns true/false if the model has translation in french.
$germany->hasTranslation('fr');

// If a german translation doesn't exist, it returns
// a new instance of CountryTranslation.
$translation = $germany->translateOrNew('de');

// Returns a new CountryTranslation instance for the selected
// language, and binds it to $germany
$translation = $germany->getNewTranslation('it');

// The eloquent model relationship. Do what you want with it ;)
$germany->translations();
```

### Fallback locales

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.

Example:

```php
return [
'use_fallback' => true,

'fallback_locale' => 'en',
];
```

You can also define *per-model* the default for "if fallback should be used", by setting the `$useTranslationFallback` property:

```php
class Country {

public $useTranslationFallback = true;

}
```

## FAQ

Expand Down Expand Up @@ -240,47 +322,3 @@ Schema::create('language_translations', function(Blueprint $table){
```

The best solution though would be to update your mysql version. And **always make sure you have the same version both in development and production environment!**

#### Can I use translation fallbacks?

If you want to fallback to a default translation if a translation has not been found, you can specify that on the model using `$model->useTranslationFallback = true`.

```php
App::make('config')->set('translatable.fallback_locale', 'en');

$country = Country::create(['code' => 'gr']);
$country->translate('en')->name = 'Greece';
$country->useTranslationFallback = true;

$country->translate('de')->locale; // en
$country->translate('de')->name; // Greece
```

You can also overwrite `useTranslationFallback` with a second parameter on `translate()`, so new translations can be created or existing ones used. Without the second parameter, `translate('de')` would return the fallback translation.

```php
App::make('config')->set('translatable.fallback_locale', 'en');

$country = Country::create(['code' => 'gr']);
$country->useTranslationFallback = true;
$country->translate('en', false)->name = 'Greece';
$country->translate('de', false)->name = 'Griechenland';

$country->translate('de')->locale; // de
$country->translate('de')->name; // Griechenland
```

When using `fill`, this is done automatically for you:

```php
$country = new Country;
$country->useTranslationFallback = true;
$country->fill([
'code' => 'gr',
'en' => ['name' => 'Greece'],
'de' => ['name' => 'Griechenland'],
]);

$country->translate('de')->locale; // de
$country->translate('de')->name; // Griechenland
```

0 comments on commit 23b7ea8

Please sign in to comment.