Getting Started with Laravel and TML

In this post we will create a very simple PHP application using the Laravel framework and translate it to a few languages using TML for PHP.

To learn about how to install and setup Laravel, please visit Laravel’s website:

http://laravel.com/docs/master/installation

Let’s create a one page site, called “Welp”. On the site we will have a few restaurant reviews and a search form.

laravel_welp_english

At the end of this guide, you will see how to use Translation Exchange tools to quickly and easily translate the app to any number of languages.

laravel_language_selector

To activate translation mode, click on “Help Us Translate” link.

laravel_inline_mode

The source code for this post can be found at:

https://github.com/translationexchange/blog/tree/master/getting-started-with-php-laravel-and-tml/welp

Let’s begin by creating a new Laravel project:

Add TML library reference by editing “composer.json” file:

To install the library, run:

Add a new “Tml.php” middleware file under “app/Http/Middleware/Tml.php” and paste the following code:

All of our navigation will be stored in the “navigation.blade.php” template. Let’s add it as well:

We want to group all strings related to the navigation into a single source. If you have multiple pages that use the navigation bar, instead of having all navigation elements to be linked to each page source, the navigation elements will only be linked to the navigation source and only the elements of the page will be linked to the page source. Notice that we open a source group on line 1 and close it on line 44. You can create any number os groups/sources, and nest them within each other.

Notice that on line 29, we add a default language selector that will show all the languages enabled/published for your application. To publish a new language, you simply need to add the language to your application from Translation Exchange dashboard, and it will be immediately visible to your translators. To make the language available to all users, publish your most recent changes through the dashboard and the latest translations and languages will be visible to everyone else.

Now we can add the actual view that uses the main layout:

Let’s look at some of the code from the above view. On line 12, we have:

We use {!! instead of {{ because we want the ability to enable inline translation mode that generates HTML wrapper tags. When you pass a token value to a tr method, you should escape it yourself, by using htmlspecialchars function.

On line 15 we use data token name city. Notice that we translate the value of the token as well. This is an example of a nested translation.

On lines 24-33, we wrap an entire HTML section with a trh function. The content will automatically be split into individual segments and translated using SDK.

On line 63, we see how a trl method is used. In this case, we deliberately don’t want to ever use an inline translator, because a translation key is used inside of a title attribute of the image tag.

It also shows how numeric context rules can be used. The line the follows also shows the numeric rules in action.

Lines 118-122 show a more advanced use of TML where we want the sentence to be translated based on the gender of user token. We also use a custom function for the “link” decoration token.

Let’s start the server by running the following command:

You should now be able to view the application, change languages, activate translation mode and contribute more translations. You can invite your own translators or order professional translations through the Translation Exchange platform.

To learn more about TML, please visit:

https://translationexchange.com/docs/tml/basics

Caching Translations

For optimal performance, translations should be cached in the application. There are two main ways to cache translations by either using static, local files based cache, or by using a shared dynamic cache, like Memcache or Redis.

The file cache must be generated and deployed with the application. When changes are made to translations or new languages are added, the cache must be updated locally, checked in with the application and deploy to the servers.

Dynamic cache can be generated and deployed without restarting the application.

In this example, we will use Memcache as our dynamic cache. To add cache to your app, update you Tml middleware to include the following directive:

Now when we restart our application, the translations will be cached in our Memcache and our application will share them across all PHP servers. But, in our case we only have one.

To invalidate the cache, we can use the following code anywhere from within our application:

Alternatively, we can create an API hook that Translation Exchange can call when a new version is released. The hook will be called with our application token so it is better to use SSL for our application.

For instance, we can setup a url “/tml/upgrade” with the following code:

This will allow us to release new translation versions or add new languages without ever needing to restart our servers.

To learn more about cache options, please visit:

https://translationexchange.com/docs/sdk/php