PHP Configuration

TML library comes with many customization options that can be adjusted based on your application needs.

Basics

One of the easiest ways to configure the TML library is to provide all of the configuration options right from within the tml_init() method.

tml_init(array(  
    "key"   => "YOUR_APPLICATION_KEY",

    "cache" => array(
        "enabled" => true,
        "adapter" => "file",
        "version" => "20160323211903",
        "version_check_interval" => 3600
    ),

    "log" => array(
        "enabled" => true,
        "severity" => "debug"
    ),

    ...

)); ?>
Name Type Required Description
key String True Your Project's Application Key
token String False Your Project's Token. This token is only necessary if your application does not have a user interface where translators can provide translations inline, like in the case of an API service.
source String False Source allows you to remap the URL path to alternative source names. See the section below for more details.

Current Locale

TML SDK provides a number of options for specifying the language in which the application request will be served. You can use a string or a hash to provide information of how the locale can be loaded and handled.

The following sections will describe each option in details.

Locale as String

If you are handling the locale loading yourself (for instance, based on the user settings) and need to force the page to be rendered in a specific language, you can set the locale as a string. You can provide the locale information in the tml init method.

tml_init(array(  
    ...
    "locale" => "ru"
    ...
));

The above code will force the page to be rendered in Russian. User will not be able to change the locale using a language selector.

Locale as Hash

If you need the locale extraction to be based on a parameter, pre-path or domain option, you can specify this using a hash. The SDK supports 4 different locale strategies.

Param Strategy

This is our default strategy, if you don't specify anything else

tml_init(array(  
    ...
    "locale" => {
      "strategy" => "param",
      "param" => "locale"
    }
    ...
));
Name Description
param Name of the parameter to be passed, like "locale=ru"

When the locale is passed as a parameter, it will be stored in a cookie so after it is set, other pages can be loaded with the same locale.

Pre-Path Strategy

The param approach with a cookie is the older and most common way to pass the locale around. But it is not SEO friendly.

Pre-path strategy allows you to specify locale as the first element in your path. For example,

https://www.sample.com/ru
https://www.sample.com/fr

You may need to configure your server or router to omit the first path elements. Once you have it setup on the routing side, use the following settings:

tml_init(array(  
    ...
    "locale" => array(
      "strategy" =>  "pre-path",
      "prefix" => "/wordpress"
    )
    ...
));
Name Description
prefix Optional. Some sites, especially WordPress bases sites, may not be hosted directly under your root path "/". So prefix can be used to specify the first path element and the URLs will be constructed as: https://www.sample.com/{prefix}/ru
Pre-Domain Strategy

This strategy is similar to pre-path but it uses the first sub-domain element for locales.

https://ru.sample.com
https://fr.sample.com

You may need to configure your server or router for this strategy. And it would be a good idea to enable cookie sharing across all your subdomains. Once you have it setup on the routing side, use the following settings:

tml_init(array(  
    ...
    "locale" => array(
      "strategy" =>  "pre-domain"
    )
    ...
));
Custom Mapping

You can make your URLs look like anythin you want using this strategy. Here you would explicitly specify which locale is server by which URL.

tml_init(array(  
    ...
    "locale" => array(
      "strategy" => "custom-domain",
      "mapping" => arra(
         "en" => "my-en.lvh.me",
         "ru" => "my-ru.lvh.me",
         "ko" => "my-ko.lvh.me"
      )
    )
    ...
));

Current Source

If your application uses dynamic url to identify resources by id or a slug, you may need to provide a mapping mechanism to ensure the TML library converts them to static source names.

TML for PHP offers 3 ways of setting a source in the init method.

Setting source as a string will force all your application strings and sub-sources to be mapped against a single source, like in the example below:

"source" => "main"

The source value can also be provided as a regular expression mapping, as follows:

"source" => array(
   '/\/users\/\\d*/' => '/users/show'
)

The above code will remap any url that matches "/users/:id" to "/users/show". If the mapping is not matched, URL path will be used instead.

If you already have your own router mapper in your application, you can implement it using a function:

"source" => function(path) (
   return myRouter->fromPath(path);
)

Caching

For best performance, all translations should be cached in your application.

"cache" => array(
        "enabled" => true,
        "adapter" => "file",
        "version" => "20160323211903"
    )

The library support many various cache options. Click here to read more about supported adapters.

Logging

If you would like to see what the SDK is doing behind the scene, you can enable Tml logging.

"log" => array(
        "enabled" => true,
        "severity" => "debug"
)

Default Data Tokens

Sometimes you may need to use the same data token values across your entire application. For instance, a name of the company is not translatable and can be used in multiple places:

<?php tre("2016 Copyright {company}", array("company" => "Translation Exchange, Inc.") ?>  

Instead of providing the same token value in every place you refer to the company, you can configure it as the default data token:

"default_data_tokens" => array(
        "company" => "Translation Exchange, Inc."
)

Now you can use the data token without having to specify its value:

<?php tre('2016 Copyright {company}') ?>  

If you need to overwrite the value for a specific case, you can still do it using the tokens hash:

<?php tre('2016 Copyright {company}', array("company" => "Google, Inc") ?>  

Default Decoration Tokens

Similarly to the data tokens, decoration tokens can also have default implementations. For instance, in the following example, bold has been preconfigured to use the strong HTML tag:

<?php tre('Welcome to [bold: my website]') ?>  

where bold has been pre-configured as:

"default_decoration_tokens" => array(
        "bold" => "<strong>{$0}</strong>"
)

In the above example, the {$0} value will be replace with the translation of 'my website'.

Another example of a more complex decoration token is a link. Consider the following example:

<?php tre("Welcome to [link: my website]", array("link" => array("href" => "www.google.com"))) %>  

where link has been pre-configured as:

"default_decoration_tokens" => array(
        "link" => "<a href='{$href}'>{$0}</a>"
)

If the value of the decoration token is passed as a hash, the hash attributes will be mapped against the named attributes in the token substitution string.

Here is another example of a custom decoration token with pre-configured value:

"default_decoration_tokens" => array(
        "colorize" => "<span style='color: {$color}'>{$0}</span>"
)
<?php tre("Welcome to [colorize: my website]", array("colorize" => array("color" => "red"))) ?>  

The following decoration tokens come pre-configured with the SDK, but you can easily change them to your liking.

array(  
 'strong' =>  '<strong>{$0}</strong>',
 'bold'   =>  '<strong>{$0}</strong>',
 'b'      =>  '<strong>{$0}</strong>',
 'em'     =>  '<em>{$0}</em>',
 'italic' =>  '<i>{$0}</i>',
 'i'      =>  '<i>{$0}</i>',
 'link'   =>  "<a href='{$href}'>{$0}</a>",
 'br'     =>  '<br>{$0}',
 'strike' =>  '<strike>{$0}</strike>',
 'div'    =>  "<div id='{$id}' class='{$class}' style='{$style}'>{$0}</div>",
 'span'   =>  "<span id='{$id}' class='{$class}' style='{$style}'>{$0}</span>"
)

Decoration tokens can also be specified using the standard HTML notation:

<?php tre('Welcome to <colorize>my website</colorize>', array("colorize" => array("color" => "red"))) ?>  

If there is no decoration token provided or no token value is specified, the HTML token will be used as is:

<?php tre('Welcome to <strong>my website</strong>') ?>