Translation

Introduction

The BF Translation Library is a high performance tool for multi-language applications. It does not required any software to manage dictionaries. The software loads the content straight from CSV files and supports APC and hash indexes. Althought, this library is integrated with the framework, can be easily used in a standalone mode in any PHP project. The library provides several advantages for developers such as:

  1. You don't need a special software to compile, encode or create your dictionary files;
  2. It supports APC, uses hash indexes and does not use any search and replace PHP functions;
  3. A hash is created with a unique text entry identifier;
  4. The translation can be used cross javascript, views, models, database and in your PHP files;
  5. No PHP methods is needed to translate strings in your application;
  6. It suppports UTF8, thus developers can delivery application in multiple languages such Greek, Japonese, etc;
  7. Recommended for high volume applications;
  8. If no correlated string is found the default base language is shown;

 

How it works

All text in your application must be written in a base language, for example english, including a small text marker to identify those strings to be translated. In the BF, an instance of the translation class is created in the index.php to define which language should be used and capture all output from your application. Then, in the final step, the library processes all output buffer translating all necessary strings, for example:

<?php

namespace modules\Clients;

use bossanova\Module\Module;

class Clients extends Module
{
    public function __default ()
    {
        echo ''; // Returns Olá Mundo
    }
}
NOTE: If there is a string with the translation marks but no corresponded translation is found in the dictionary, the original text will be used.

 

Languages

All classes extended from Module Library will have some native methods to handle with dynamic translations.

Get current language

There are two ways to get the current language in use. The first one, is using the locate() method, for example:

<?php

namespace modules\Clients;

use bossanova\Module\Module;

class Clients extends Module
{
    public function __default ()
    {
        // Get the current language in use
        echo $this->locate();
    }
}

The second one, is perform a GET request to any module passing locale as the second URL argument, for example:
http://localhost/clients/locale

 

Change the current language

There are two ways to change the language from your application. The first one, is using the native $locate( [string]$locale ) as follow:

<?php

namespace modules\Clients;

use bossanova\Module\Module;

class Clients extends Module
{
    public function __default ()
    {
        // Change the language for portuguese and load the dictionary: /library/pt_BR.csv
        $this->locale('pt_BR');
    }
}

The second option is perform a request to your module passing locale as the second URL argument, and which language you would like to use, for example:
http://localhost/clients/locale/fr_FR
 

NOTE: All locale should be related to a dictionary file, so it is only possible to change the language if the related dictionary is found.

 

Dictionaries

When a language is selected to be used, the corresponded dictionary file will be loaded to the session/cache. So, all dictionary files should be available in the folder library/Translate, for example:

resources/locales/en_GB.csv
resources/locales/pt_BR.csv
resources/locales/fr_FR.csv
resources/locales/es_ES.csv

Each dictionary should contain all strings in the base language and the corresponded translation. Every line in the file is one string in the base and in the corresponded language separated by pipeline, as follow:

Hello World|Olá Mundo
My name is|Meu nome é
This is a sample phrase to be translated|Essa é um frase simples para ser traduzida
Another|Outro
Login|Acessar
Back|Voltar
(...)
NOTE: Bear in mind to keep always your CSV as UTF-8 to avoid encoding problems.

 

Strings to be included in your dictionary

To help developers not lose track of what need to be translated, the Translate Library has a very useful tool to present all entries should be include in the dictionary files.

// Create the instance of the translation class
$translate = new Translate();

// Will return all strings to be includeded in your dictionary files
$translate->search();

Translate from a variable

There some special situations where you need to translate a string that need to be translated. For example, developers would like to translate a marketing email text before send to a user:

<?php

namespace modules\Clients;

use bossanova\Module\Module;

class Clients extends Module
{
    public function marketing ()
    {
        // Get the id from http://localhost/clients/marketing/xx
        $id = $this->getParam(2);

        // Loading client information
        $client = new \models\Clients;
        $row = $client->getById($id);

        // Loading recovery email body
        $content = file_get_contents("resources/texts/email_marketing.txt");

        // Translate it
        $content = Translate->run($content, [$locale is optional]);

        // Sendmail
        $this->sendmail($row['user_email'], $row['user_name'], "Marketing", $content);
    }
}

Standalone Usage

Minimum standalone usage

<?php

// Start session
session_start();

// Add the file in your project (download from http://github/bossanova-framework)
require_once "vendors/bossanova/Translate/Translate.class.php";

// Default language of the application
if (!isset($_SESSION[‘locale’])) $_SESSION[‘locale’] = ‘en_GB’;

// Create the instance
$translate = new Translate();

// Translate everything after this point
$translate->load($_SESSION[‘locale’]); // Render your final application in en_GB

// Any code
$name = "Bossanova";

// Some other code
echo "";
echo "My name is" . $name;