Changes

Page history
add pop-up edit title translations from PHP to JS authored by Vladimir Schneider's avatar Vladimir Schneider
Hide whitespace changes
Inline Side-by-side
Installation.md
View page @ 6ea9e6a5
1. Require this package in your composer.json and run composer update (or run `composer require 1. Require this package in your composer.json and run composer update (or run `composer require
vsch/laravel-translation-manager:*` directly): vsch/laravel-translation-manager:*` directly):
```json ```json
"require": { "require": {
"vsch/laravel-translation-manager": "~2.2" "vsch/laravel-translation-manager": "~2.2"
} }
``` ```
- if you are not going to be customizing the web interface it is highly recommended that you if you are not going to be customizing the web interface it is highly recommended that you
add automatic asset publishing for this package after upgrade in your project's add automatic asset publishing for this package after upgrade in your project's
composer.json: composer.json:
```json ```json
"scripts": { "scripts": {
"post-update-cmd": [ "post-update-cmd": [
... other stuff ... ... other stuff ...
"php artisan vendor:publish --provider=\"Vsch\\TranslationManager\\ManagerServiceProvider\" --tag=public", "php artisan vendor:publish --provider=\"Vsch\\TranslationManager\\ManagerServiceProvider\" --tag=public",
... other stuff ... ... other stuff ...
] ]
}, },
``` ```
Otherwise a future update, that needs new assets, will not work properly. composer does not Otherwise a future update, that needs new assets, will not work properly. composer does not
run post-update scripts of packages. run post-update scripts of packages.
Here is a full scripts section of a standard Laravel 5.1 project composer.json should look Here is a full scripts section of a standard Laravel 5.1 project composer.json should look
like after the change. like after the change.
```json ```json
{ {
"scripts": { "scripts": {
"post-install-cmd": [ "post-install-cmd": [
"php artisan clear-compiled", "php artisan clear-compiled",
...@@ -50,103 +50,99 @@ ...@@ -50,103 +50,99 @@
] ]
} }
} }
``` ```
2. After updating composer, add the ServiceProviders to the providers array in config/app.php 2. After updating composer, add the ServiceProviders to the providers array in config/app.php
and comment out the original TranslationServiceProvider: and comment out the original TranslationServiceProvider:
```php ```php
//Illuminate\Translation\TranslationServiceProvider::class, //Illuminate\Translation\TranslationServiceProvider::class,
Vsch\TranslationManager\ManagerServiceProvider::class, Vsch\TranslationManager\ManagerServiceProvider::class,
Vsch\TranslationManager\TranslationServiceProvider::class, Vsch\TranslationManager\TranslationServiceProvider::class,
//Vsch\UserPrivilegeMapper\UserPrivilegeMapperServiceProvider::class, //Vsch\UserPrivilegeMapper\UserPrivilegeMapperServiceProvider::class,
Collective\Html\HtmlServiceProvider::class, Collective\Html\HtmlServiceProvider::class,
``` ```
The TranslationServiceProvider is an extension to the standard functionality and is required The TranslationServiceProvider is an extension to the standard functionality and is required
in order for the web interface to work properly. It is backward compatible with the existing in order for the web interface to work properly. It is backward compatible with the existing
Translator since it is a subclass of it and only overrides implementation for new features. Translator since it is a subclass of it and only overrides implementation for new features.
##### Removing dependency on UserPrivilegeMapper from service providers array ##### Removing dependency on UserPrivilegeMapper from service providers array
**If you are upgrading from version 2.0.x of LTM** you need to remove the dependency to **If you are upgrading from version 2.0.x of LTM** you need to remove the dependency to
UserPrivilegeMapper from your application service providers, shown commented out above. UserPrivilegeMapper from your application service providers, shown commented out above.
3. add the Facade to the aliases array in config/app.php: 3. add the Facade to the aliases array in config/app.php:
```php ```php
'Form' => Collective\Html\FormFacade::class, 'Form' => Collective\Html\FormFacade::class,
'Html' => Collective\Html\HtmlFacade::class, 'Html' => Collective\Html\HtmlFacade::class,
``` ```
##### Removing dependency on UserPrivilegeMapper from facade alias array ##### Removing dependency on UserPrivilegeMapper from facade alias array
**If you are upgrading from version 2.0.x of LTM** you need to remove the dependency to **If you are upgrading from version 2.0.x of LTM** you need to remove the dependency to
UserPrivilegeMapper from your application facade alias array, shown commented out above. UserPrivilegeMapper from your application facade alias array, shown commented out above.
4. 4.
##### Publishing and running migrations ##### Publishing and running migrations
You need to publish then run the migrations for this package: You need to publish then run the migrations for this package:
```bash ```bash
$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=migrations $ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=migrations
$ php artisan migrate $ php artisan migrate
``` ```
If you want to create translation tables in another database you will need to do it manually
If you want to create translation tables in another database you will need to do it manually or setup a connection name with the default database you want to use and apply the migration
or setup a connection name with the default database you want to use and apply the migration to it specifically:
to it specifically:
```bash ```bash
$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=migrations $ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=migrations
$ php artisan migrate --database="connection_name" $ php artisan migrate --database="connection_name"
``` ```
Where `connection_name` is the name of the connection to use for the migrations. You will
Where `connection_name` is the name of the connection to use for the migrations. You will also need to configure the translation manager to use this as the default connection for
also need to configure the translation manager to use this as the default connection for translation related tables. See
translation related tables. See [[Changing the database name|Configuration#changing-the-database-name]]
[[Changing the database name|Configuration#changing-the-database-name]]
5.
5. ##### Publishing the configuration
##### Publishing the configuration
You need to publish the config file for this package. This will add the file
You need to publish the config file for this package. This will add the file `config/laravel-translation-manager.php`
`config/laravel-translation-manager.php`
```bash
```bash $ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=config
$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=config ```
```
6. You need to publish the web assets used by the translation manager web interface. This will 6. You need to publish the web assets used by the translation manager web interface. This will
add the assets to `public/vendor/laravel-translation-manager` add the assets to `public/vendor/laravel-translation-manager`
```bash ```bash
$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=public $ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=public
``` ```
7. 7.
##### Configuring WebUI Route ##### Configuring WebUI Route
By default the web interface of the translation manager is no longer mapped to a route. To By default the web interface of the translation manager is no longer mapped to a route. To
make it available at `http://yourdomain.com/translations`. Add the following to your make it available at `http://yourdomain.com/translations`. Add the following to your
`routes/web.php` file: `routes/web.php` file:
```php ```php
use Vsch\TranslationManager\Translator; use Vsch\TranslationManager\Translator;
\Route::group(['middleware' => 'web', 'prefix' => 'translations'], function () { \Route::group(['middleware' => 'web', 'prefix' => 'translations'], function () {
Translator::routes(); Translator::routes();
}); });
``` ```
Change the middleware and/or the prefix to adjust it to your site's requirements.
Change the middleware and/or the prefix to adjust it to your site's requirements.
If your `config/laravel-translation-manager.php` is of an earlier version you can delete the If your `config/laravel-translation-manager.php` is of an earlier version you can delete the
route related entries from it. These are no longer used: route related entries from it. These are no longer used:
```php ```php
/* /*
|-------------------------------------------------------------------------- |--------------------------------------------------------------------------
| Routes group config | Routes group config
|-------------------------------------------------------------------------- |--------------------------------------------------------------------------
...@@ -158,51 +154,50 @@ ...@@ -158,51 +154,50 @@
'prefix' => 'translations', 'prefix' => 'translations',
'middleware' => ['web', 'auth'], 'middleware' => ['web', 'auth'],
], ],
``` ```
8.
8. ##### Setting up user authorization
##### Setting up user authorization
TranslationManager uses Laravel 5.2 abilities for providing authorization for various
TranslationManager uses Laravel 5.2 abilities for providing authorization for various translation functions. These abilities can be defined in the app's
translation functions. These abilities can be defined in the app's `AuthServiceProvider::boot` function, see example below.
`AuthServiceProvider::boot` function, see example below.
You need to define the following abilities:
You need to define the following abilities:
* `ltm-admin-translations` true/false if user can administer translations only used if
- `ltm-admin-translations` true/false if user can administer translations only used if `admin_translations` option is set to true in LTM config.
`admin_translations` option is set to true in LTM config.
* `ltm-bypass-lottery` true/false if user bypasses the missing key lottery and all missing
- `ltm-bypass-lottery` true/false if user bypasses the missing key lottery and all missing keys are displayed for the user.
keys are displayed for the user.
* `ltm-list-editors` true/false, if user can manage per locale user list. This one is
- `ltm-list-editors` true/false, if user can manage per locale user list. This one is optional and only used if you have `user_locales_enabled` set to `true` in the config file.
optional and only used if you have `user_locales_enabled` set to `true` in the config See:
file. See: [Enabling per locale user access control](Configuration#enabling-per-locale-user-access-control)
[Enabling per locale user access control](Configuration#enabling-per-locale-user-access-control)
this ability function takes 3 arguments:
this ability function takes 3 arguments:
1. `$user` - the currently logged in user
1. `$user` - the currently logged in user
2. `$connection_name` - current connection name, '' or null means default
2. `$connection_name` - current connection name, '' or null means default
3. `&$user_list` - reference in which to return the list of users that can be managed by
3. `&$user_list` - reference in which to return the list of users that can be managed by the currently logged in user.
the currently logged in user.
This should only return a list of users that have access to the translation manager web
This should only return a list of users that have access to the translation manager UI. Please keep in mind that by default a user can modify any locale if there is no
web UI. Please keep in mind that by default a user can modify any locale if there is entry for this user in the `ltm_user_locales` table or if the entry is null or empty. By
no entry for this user in the `ltm_user_locales` table or if the entry is null or this measure the table contains entries for users wih limited access. Any user that has
empty. By this measure the table contains entries for users wih limited access. Any access to translation manager web UI and no entry in the `ltm_user_locales` table will
user that has access to translation manager web UI and no entry in the be able to edit translations in any locale. If you don't want a user to access any
`ltm_user_locales` table will be able to edit translations in any locale. If you locales then they should not have access to the LTM web UI through the Laravel
don't want a user to access any locales then they should not have access to the LTM middleware authorization mechanism.
web UI through the Laravel middleware authorization mechanism.
Here is an example implementing these abilities in the app's `AuthServiceProvider::boot`
Here is an example implementing these abilities in the app's `AuthServiceProvider::boot` function:
function:
```php
```php $gate->define('ltm-admin-translations', function ($user) {
$gate->define('ltm-admin-translations', function ($user) {
/* @var $user \App\User */ /* @var $user \App\User */
return $user && $user->is_admin; return $user && $user->is_admin;
}); });
...@@ -226,23 +221,24 @@ ...@@ -226,23 +221,24 @@
// if the returned list is empty then no per locale admin will be shown for the current user. // if the returned list is empty then no per locale admin will be shown for the current user.
return $user_list; return $user_list;
}); });
``` ```
In this example the User model implements two attributes: is_admin and is_editor. The admin
In this example the User model implements two attributes: is_admin and is_editor. The admin user is allowed to manage translations: import, delete, export, etc., the editor user can
user is allowed to manage translations: import, delete, export, etc., the editor user can only edit existing translations. However, both of these users will always log missing
only edit existing translations. However, both of these users will always log missing translation keys so that any missing translations will be visible to them instead of relying
translation keys so that any missing translations will be visible to them instead of relying on the session winning the missing key lottery before logging missing keys.
on the session winning the missing key lottery before logging missing keys.
**If you are upgrading from version 2.0.x of LTM** you need to remove the UserPrivilegeMapper
**If you are upgrading from version 2.0.x of LTM** you need to remove the definitions added in your application, probably in `app/Providers/AppServiceProvider.php`
UserPrivilegeMapper definitions added in your application, probably in
`app/Providers/AppServiceProvider.php` 9.
##### Yandex assisted translations
9. Yandex assisted translations requires setting the `yandex_translator_key` to your Yandex API
key in the `config/laravel-translation-manager.php` file, it is free to get and use. See: Assisted translations requires setting the `yandex_translator_key` to your Yandex API key in
the `config/laravel-translation-manager.php` file, it is free to get and use. See:
<https://tech.yandex.com/translate/> <https://tech.yandex.com/translate/>
10. 10.
##### Overriding the Web Interface Translations ##### Overriding the Web Interface Translations
If you want to override the Translation Manager web interface translations or add another If you want to override the Translation Manager web interface translations or add another
...@@ -251,11 +247,10 @@ ...@@ -251,11 +247,10 @@
```bash ```bash
$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=lang $ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=lang
``` ```
This will copy the translations to your project and allow you to view/edit them in the This will copy the translations to your project and allow you to view/edit them in the
translation manager web interface. translation manager web interface.
11. 11.
##### Customizing Views ##### Customizing Views
If you want to customize views for the Translation Manager web interface you will need to If you want to customize views for the Translation Manager web interface you will need to
...@@ -264,12 +259,11 @@ ...@@ -264,12 +259,11 @@
```bash ```bash
$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=views $ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=views
``` ```
This will copy the views to your project under the This will copy the views to your project under the
`resources/views/vendor/laravel-translation-manager` directory. See: `resources/views/vendor/laravel-translation-manager` directory. See:
[[Modifying the default Views|Configuration#modifying-the-default-views]] [[Modifying the default Views|Configuration#modifying-the-default-views]]
12. 12.
##### Markdown to HTML conversion ##### Markdown to HTML conversion
This option can be used to automatically convert translations for keys with a given suffix This option can be used to automatically convert translations for keys with a given suffix
...@@ -278,7 +272,7 @@ ...@@ -278,7 +272,7 @@
also install a package that does the HTML conversion. See also install a package that does the HTML conversion. See
[[Markdown to HTML conversion|Configuration#markdown-to-html-conversion]] [[Markdown to HTML conversion|Configuration#markdown-to-html-conversion]]
13. 13.
##### Enabling Edit In-Place on you pages ##### Enabling Edit In-Place on you pages
Allowing edit in-place of your site's pages will require some modification to views to Allowing edit in-place of your site's pages will require some modification to views to
... ...
......