Installation - vsch/laravel-translation-manager GitHub Wiki

Require this package in your composer.json and run composer update (or run composer require vsch/laravel-translation-manager:* directly):

"require": {
     "vsch/laravel-translation-manager": "~2.2"
 }

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 composer.json:

"scripts": {
     "post-update-cmd": [
         ... other stuff ...
         "php artisan vendor:publish --provider=\"Vsch\\TranslationManager\\ManagerServiceProvider\" --tag=public" --force,
         ... other stuff ...
     ]
 },

Otherwise a future update, that needs new assets, will not work properly. composer does not run post-update scripts of packages.

:warning: React UI assets require that they are updated with every upgrade to make sure the React UI is in sync with the server code. It is highly recommended that you add publishing of public assets on upgrade.

Here is a full scripts section of a standard Laravel 5.1 project composer.json should look like after the change.

{
     "scripts": {
         "post-install-cmd": [
             "php artisan clear-compiled"
         ],
         "pre-update-cmd": [
             "php artisan clear-compiled"
         ],
         "post-update-cmd": [
             "php artisan vendor:publish --provider=\"Vsch\\TranslationManager\\ManagerServiceProvider\" --tag=public --force"
         ],
         "post-root-package-install": [
             "php -r \"copy('.env.example', '.env');\""
         ],
         "post-create-project-cmd": [
             "php artisan key:generate"
         ]
     }
 }

After updating composer, add the ServiceProviders to the providers array in config/app.php and comment out the original TranslationServiceProvider:

//Illuminate\Translation\TranslationServiceProvider::class,
 Vsch\TranslationManager\ManagerServiceProvider::class,
 Vsch\TranslationManager\TranslationServiceProvider::class,
 //Vsch\UserPrivilegeMapper\UserPrivilegeMapperServiceProvider::class,
 Collective\Html\HtmlServiceProvider::class,

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 Translator since it is a subclass of it and only overrides implementation for new features.

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 UserPrivilegeMapper from your application service providers, shown commented out above.

add the Facade to the aliases array in config/app.php:

'Form'      => Collective\Html\FormFacade::class,
'Html'      => Collective\Html\HtmlFacade::class,

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 UserPrivilegeMapper from your application facade alias array, shown commented out above.

Publishing and running migrations

You need to publish then run the migrations for this package:

$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=migrations
 $ php artisan migrate

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 to it specifically:

$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=migrations
 $ php artisan migrate --database="connection_name"

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 translation related tables. See Changing the database name

Publishing the configuration

You need to publish the config file for this package. This will add the file config/laravel-translation-manager.php

$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=config

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

$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=public --force

Configuring WebUI Route

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 routes/web.php file:

use Vsch\TranslationManager\Translator;

 \Route::group(['middleware' => 'web', 'prefix' => 'translations'], function () {
     Translator::routes();
 });

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 route related entries from it. These are no longer used:

/*
  |--------------------------------------------------------------------------
  | Routes group config
  |--------------------------------------------------------------------------
  |
  | The default group settings for the elFinder routes.
  |
  */
  return array(
      'route' => [
          'prefix' => 'translations',
          'middleware' => ['web', 'auth'],
      ],
  );

React App Configuration

Starting with version 2.6.16, a react app is available for the LTM UI. Its URL is /ui appended to the above route URL. Mix manifest lines need to exist in order for mix to be able to find the application assets.

The configuration depends on whether you use mix on your project and whether you want to include compiled version of the LTM UI app or build them as part of your project. In all cases it is a matter of adding a few lines described in React App UI.

:warning: A new migration was added to support persistence of user's app configuration options. Make sure you did not skip the Publishing and running migrations step if you are upgrading.

Setting up user authorization

TranslationManager uses Laravel 5.2 abilities for providing authorization for various translation functions. These abilities can be defined in the app's AuthServiceProvider::boot function, see example below.

You need to define the following abilities:

• ltm-admin-translations true/false if user can administer translations only used if 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 keys are displayed for the user.

• 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. See: Enabling per locale user access control

  this ability function takes 3 arguments:

  1. $user - the currently logged in user

  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 the currently logged in user.

     This should only return a list of users that have access to the translation manager web UI. Please keep in mind that by default a user can modify any locale if there is no entry for this user in the ltm_user_locales table or if the entry is null or empty. By this measure the table contains entries for users wih limited access. Any user that has access to translation manager web UI and no entry in the ltm_user_locales table will be able to edit translations in any locale. If you don't want a user to access any locales then they should not have access to the LTM web UI through the Laravel middleware authorization mechanism.

Here is an example implementing these abilities in the app's AuthServiceProvider::boot function:

$gate->define('ltm-admin-translations', function ($user) {
     /* @var $user \App\User */
     return $user && $user->is_admin;
 });

 $gate->define('ltm-bypass-lottery', function ($user) {
     /* @var $user \App\User */
     return $user && ($user->is_admin || $user->is_editor);
 });

 $gate->define('ltm-list-editors', function ($user, $connection_name, &$user_list) {
     /* @var $user \App\User */
     /* @var $connection_name string */
     /* @var $query  \Illuminate\Database\Query\Builder */
     $query = $user->on($connection_name)->getQuery();

     // modify the query to return only users that can edit translations and can be managed by $user
     // if you have a an editor scope defined on your user model you can use it to filter only translation editors
     //$user_list = $user->scopeEditors($query)->orderby('id')->get(['id', 'email', 'name']);
     $user_list = $query->orderby('id')->get(['id', 'email']);

     // if the returned list is empty then no per locale admin will be shown for the current user.
     return $user_list;
 });

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 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 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 definitions added in your application, probably in app/Providers/AppServiceProvider.php

Yandex assisted translations

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/

Overriding the Web Interface Translations

If you want to override the Translation Manager web interface translations or add another locale you will need to publish the language files to your project by executing:

$ 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 translation manager web interface.

Customizing Views

If you want to customize views for the Translation Manager web interface you will need to publish the views to your project by executing:

$ php artisan vendor:publish --provider="Vsch\TranslationManager\ManagerServiceProvider" --tag=views

This will copy the views to your project under the resources/views/vendor/laravel-translation-manager directory. See: Modifying the default Views

Markdown to HTML conversion

This option can be used to automatically convert translations for keys with a given suffix to HTML and store the result for a key with the suffix removed. Can be used for translations that contain HTML. By default this option is disabled. Enabling it would require that you also install a package that does the HTML conversion. See Markdown to HTML conversion

Enabling Edit In-Place on you pages

Allowing edit in-place of your site's pages will require some modification to views to support this functionality Markdown to HTML conversion