Skip to content

Configuration

Jump to bottom
Vladimir Schneider edited this page Jan 5, 2017 · 47 revisions

The config file config/laravel-translation-manager.php has comments that provide a description for each option. Note that when admin_enabled is set to false then translation management is limited to editing existing translations all other operations have to be done through the command line. Ideally, this option needs to be dynamic based on user privileges so that translators cannot delete translations or administer translations but admins can. See Installation: step 8.

By default the primary locale is en. The primary locale determines what language is used for the source text for the translate button in the edit pop-up and can be changed in the web interface for the current session. When editing the text for the primary locale a button in the edit pop-up allows you to convert the text of the key to a default value (change . - _ to spaces, capitalize first letter of each word) that way you can generate descent placeholder text to continue development and replace it with more meaningful value later.

By default the configuration will load all translations found in the standard Laravel locations. Below {vendor}, {package}, {locale}, {group} are placeholders for their corresponding values referring to vendor name, package name, locale string and translation group. The translation group will consist of optional sub-directory tree and the file name, allowing you to organize your translation files.

/resources/lang/{locale}/{group}.php : Standard project translation files

/resources/lang/vendor/{package}/{locale}/{group} : Package translation override files.

/workbench/{vendor}/{package}/resources/lang/{locale}/{group} : Translation files for packages that you are developing in the current project. Laravel 4.2 style but the directory layout updated to version 5 standard. These will have a group prefix of wbn: in the database and web interface to distinguish them from the standard Laravel package namespaces.

/vendor/{vendor}/{package}/resources/lang/{locale}/{group} : Translation files for packages that are dependents of your project. By default no translation files are loaded from this section. You will need to edit the configuration file for the 'vendor' section and list the packages you want to include in the 'include' array in the form 'vendor/package'. These will have a group prefix of vnd: in the database and web interface to distinguish them from the standard Laravel package namespaces

The default configuration file also has entries for two packages whose translation files' location and naming convention does not follow Laravel conventions and require more tweaking to allow import/export of their language files. These non-standard layouts can only be included in the wbn: or vnd: prefixed namespaces.

Modifying the default Views

If you published the views to your project in Installation: step 11 then you can customize them to your liking. The package view directory also contains a layouts/master.blade.php file for a default layout. The intent is for you to provide your own master layout that the index.blade.php will extend so it can match your site's style.

Enabling per locale user access control

Admin users, Auth::user()->can('ltm-admin-translations') returns true, can modify, delete, create translation in all locales.

By default, users who are not administrators, ie. Auth::user()->can('ltm-admin-translations') returns false, can modify translations for all locales.

To enable per locale access control for these users you need to set user_locales_enabled in the configuration file to true and configure per user locales in the ltm_user_locales table. The user locales are indexed by currently logged in user's id.

You will need to provide the ltm-list-editors ability, in addition to the other ltm- prefixed abilities:

  • ltm-admin-translations true/false if user can administer translations

  • 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 the ability function takes 3 parameters:

    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.

These abilities should be defined in the app's AuthServiceProvider::boot function. Here is an example:

$gate->define('ltm-admin-translations', function ($user) {
    /* @var $user \App\User */
    // modify the code below to return true for users that can administer translations
    return $user && $user->is_admin;
});

$gate->define('ltm-bypass-lottery', function ($user) {
    /* @var $user \App\User */
    // modify the code below to return true for users that can administer translations
    // or edit translation so that missing keys will be logged for all sessions of
    // these users instead of one out of N sessions as given by random lottery result 
    return $user && ($user->is_admin || $user->is_editor);
});

$gate->define('ltm-list-editors', function ($user, $connection_name, &$user_list) {
    /* @var $connection_name string */
    /* @var $user \App\User */
    /* @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 = $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;
});

⚠️ If the user id is not found in the table or if the locales list is null or empty then the user will have access to all locales.

Column Type Description
user_id unsigned integer value returned by Auth::id()
locales text comma separated list of locales the user is allowed to modify. null or an empty string means can modify any locale.

Users who do not have access to a locale will not be allowed to modify its translations. They will see these translations as text instead of a link that opens the edit pop-up.

Changing the database name

If you have your translation table(s) in a database other than the default used by the default connection you will need to define another database connection that has this database as the default and define a default connection to use the for translation manager database access. By default this is will be the default database connection defined in your Laravel database config file.

Laravel 5 does not handle changing the connection's database consistently. Previous attempts to allow overriding the database name via the config file produced inconsistent results.

    /**
     * used to provide an alternate default connection name for translation
     * tables
     *
     * @type string     connection name to use for the default connection
     *
     * if blank, null or not defined then default connection will be used.
     *
     */

    'default_connection' => 'mysql_laravel5',

Setting up alternate database connections

If you want to be able to access multiple databases for the translation manager from one set of language files you can configure the db_connections option in the config file. Here is what I use to access the production server's translations from my local development environment:

    /**
     * @type array      list of alternate database connections and their properties indexed by app()->environment() value,
     *                  default connection settings are taken from config, so only add alternate connections
     *
     *                  If user_list_connection is missing, null or empty then the connection will also be used
     *                  to obtain the user list for user locale management
     *
     *                  description is used to display the connection name, default connection is displayed as 'default' in
     *                  the web interface.
     *
     *                  indatabase_publish of:
     *                  0 - means use files only and publish to files.
     *                  1 - means use cache for publishing modifications. No files are written out
     *                  2 - means use cache for publishing modifications but also write out the files.
     *                      useful for publishing to files while leaving all flags in the database as
     *                      they would be after publishing only to cache.
     */
    'db_connections' => array(
        'local' => array(
            'mysql_prd' => array(
                'description' => 'production',
                'indatabase_publish' => 2,
                //'user_list_connection' => '',
            ),
        ),
    ),

The option is an array of environment names which in turn contain database connection names which list the options to use for that connection.

description : the string to use in the web interface combo box to represent this connection. If the description is empty or missing then the connection name will be used.

indatabase_publish : the setting for indatabase_publish to use for this connection. If this option is missing then the global configuration indatabase_publish will be used. Setting this value to 2, will write to the local translation files but leave the database in a state to serve changed translations from the cache. Note that with indatabase_publish set to 1 or 2 publishing will not reset the changed flag for translations and these will continue to show up in the dashboard as changed.

* `0`: use files only and publish to files.
* `1`: use cache for publishing modifications. No files are written out
* `2`: use cache for publishing modifications but also write out the files. Useful for
  publishing to files while leaving all flags in the database as they would be after
  publishing only to cache.

user_list_connection : the connection name to use for this connection when retrieving the user list for user access admin. If this entry is missing, null or an empty string then the connection name used for translation manager tables will be used for user list retrieval. Only used if user_locales_enabled is true.

* After updating the remote translations you need to go into translations page on the remote
  server and do a `publish all` so that either the files or the cache is updated with new
  translations.

* After deploying a new version of the application, with updated translation files on the
  servers, you should do an `Import` with `Only add new translations`. This will import any
  new translations and reset the cache.

Markdown to HTML conversion

By default the markdown_key_suffix option is disabled. Enabling it would require that you also install a package that does the HTML conversion. The code currently assumes that this conversion is done via the Markdown facade using the \Markdown::convertToHtml($markdown) call. GrahamCampbell/Laravel-Markdown serves this purpose well. You will need to install this package or implement the facade to use another markdown to HTML converter, if you want to enable this option.

This option is for now experimental. ie. Evolving. There are a few limitations:

  • With this option set to a suffix string, all keys that end in this suffix, will have their text converted to HTML. The resulting HTML text will be saved in a key, with the suffix removed. For example, with the suffix set to '-md', a translation for the key license.email-body-md will be converted to HTML and the resulting text saved for the license.email-body.

  • This conversion is ONLY done when the translation for the markdown key is modified via the web UI. Keys already in the translation files or in the database are assumed to be properly converted.

  • A new button will appear in the edit pop-up for markdown keys: Screen Shot edit clean markdown

    This button removes unnecessary line breaks in the translation text or a selected part of it. Uses very rudimentary string manipulation and not proper markdown parsing. No checking is done for code fences, tables or verbatim blocks.

  • Set this to a reasonable suffix that will not conflict with normal keys in your application , with laravel translation key convention and LTM package operation. Some options that work are: '-md', '--md', '-md-'

  • Do not use:

    • '.md' or anything with a period. It denotes a nested array key for translations.
    • multi-byte characters in the suffix. non-multi-byte string operations are used in manipulating the key.
    • keys that will cause issues in jQuery because keys are used to create jQueries with keys assumed to be valid element id's
    • colons : since these are used to delimit package translation groups
    • any suffix with +, @ these fail in the JavaScript code used in the web UI.

    You get the picture. Try a suffix out and if it works for you great. If not try another one or if you are up to it, fix the code to handle the failing suffix and post a PR.

Enabling Edit In-Place on Site Pages

Edit in place mode allows editing of translations right in the page where they are located. Sometimes it is more convenient to fix a translation where you see it instead of trying to find the key that is used for the display string. See: Enabling Edit In Place On Site Pages

Clone this wiki locally