TraducTeurk

1 The management of translations in a PHP framework

1.1 Generaly speaking

When we develop a web application in a PHP framework, we are driven to manage labels, error messages, etc... which must be translated into the tongue of the internaut if it is not the one of the implementation of the application.

There are many ways to manage this thing, the most common being:

Store all the labels in a DB table, along with their translations in the languages handled by the website, and use the DB ID of the label in the PHP source code.
Use the label as the parameter of a function call that will return its translation into the browsing language -this function is simply using an array to associate the translated label to the original one.

1.2 Translations in FrameBeurk

Beginning with version 0.6, FrameBeurk implements the second solution. A label to get translated on the run is handled that way in the source code:
Beurk_traduit('Liste des ressources');
FrameBeurk is designed to assemble in the same website different applications named Modules. The existing modules are for examples Beurk, Rhum and Dnlod. In its configuration file, each module declares the language in which all its labels are defined.
For example, for the Dnlod module, the file configDnlod.php contains:
$CONFIG['Module']['Dnlod'] = array( 'ChargerFonctions' => false, 'Langue' => 'fr_FR');

As it is placed in an action of module Dnlod, the language of the label 'Liste des ressources' of the instruction above is fr_FR.
It may be usefull to use a label defined by another module or to insert a varying part in the label (e.g. number of page). Therefore, function Beurk_traduit accepts optional arguments:
Beurk_traduit(' p.%d', 'Beurk', $NoPage)

Even if the instruction above is present in module Dnlod, the label ' p.%d' belongs to module Beurk (and so is declared in the implementation tongue of module Beurk). %d will be replaced by the content of variable $NoPage at the execution.
To avoid making the code too much clumsy, with too many Beurk_traduit, it is possible to create as many functions as needed that accept a label to translate for argument.
Kom1_actionVueMaj('Ajouter une ressource', array('ActVue' => 'cree', 'IdVue' => 'Ressource'))

The instruction above is inserting in the html page a link to the view creeRessource. This instruction is present in an action of module Dnlod. Therefore, the label 'Ajouter une ressource' belongs to module Dnlod and is declared in the tongue of this module (fr_FR), regardless of the fact that it is a calling parameter of a function of module Kom1.
By the way, it is function Kom1_actionVueMaj that will manage the translation of this label by calling Beurk_traduit.
This quite trivial function, in order to replace the received label by its translation, is loading an associative array named catalog wich is defined for each module.
For example, for the translations into en_US of module Dnlod (which is declared in fr_FR), the file catalogueDnlod_en_US.php defines:
$CATALOG['en_US']['Dnlod'] = array( '%d téléchargement%s' => '%d download%s', .../... 'Ajouter une ressource' => 'Add ressource', 'Ajouter une Version' => 'Add version', .../... );

The constitution and the maintenance of catalogs would be tedious without a tool. This is where comes out TraducTeurk...

2 TraducTeurk: The translation management tool

TraducTeurk is the Excel-VBA application that simplifies the management of the translations in FrameBeurk. It extracts the labels to translate from the source code of the PHP framework and gathers them into an Excel worksheet, sorted by module. If some translations are already available in the existing catalog files, TraducTeurk completes the worksheet with them.

After that, the developer -or the person in charge, completes the sheet with the missing translations, then requests TraducTeurk to generate the new catalog files. The last thing left to do is to copy these catalog files at the right place into the FrameBeurk tree folder, so that the translations are taken into account.

2.1 The command worksheet

The command worksheet is the user interface -quite simple, of TraducTeurk. Here we fill in the sheet names where the software is to work, the parameters it has to use, the folder to use, and here we run the actions that TraducTeurk must do. Worksheets and parameters have preset default values that do not need to be modified.

The worksheets
- Functions with labels (functions) : This is the sheet where to declare the functions that accept labels to translate
- List of the files (Fmbk) : As a bonus, TraducTeurk writes on this sheet the name of the folders and files that are scanned during the extracting phase.
- Analysed code (debug) : Another bonus, TraducTeurk copies here the analysed code, tokenized, and puts forward the labels it has detected.
- Labels (Libelles) : This is here that the extracted labels are gathered and where the user completes the new translations or corrects the existing ones.
The parameters
- Prefix of the catalog files (catalogue) : The names of all the catalog files (and only these files) in the FrameBeurk folder tree must begin with this prefix.
- Line Feed character (CrLf) : The one which will be used during the generation of the catalog files.
- Default module (Beurk) : If the module is not given with the label, TraducTeurk considers that the label is attached to the module it is currently scanning. But if it is outside any module, it attaches the label to this module by default.
- Folder of the modules (Module) : In the folder tree of FrameBeurk, a folder directly inside this folder is considered to be a module folder.
- Array of catalogs ($CATALOG) : A catalog file generated by TraducTeurk is simply the declaration of a PHP variable of associative array data type. This is the name of this variable.
The folders
- Input : This is the full path of the folder where to extract the labels (usually, it is the installation path of FrameBeurk).
- Output : Where the catalog files will be generated (it is up to the TraducTeurk user to move them afterward).
The actions
- Run the extraction process : TraducTeurk loads the names of the functions to examine, scans the input folder tree (and write its content in the dedicated worksheet), analyses the PHP code (idem) and gathers all labels to translate into Excel.
- Generate the catalogs : TraducTeurk generates the catalog files from the labels present in the Excel worksheet.

2.2 The functions to look after

This sheet contains the list of FrameBeurk functions (as of version 0.65) that accept as argument a label eligible to translation. For each function are defined the position of the label in the function signature and the one of the module (if the function accepts this argument). Only the arguments of string data type are selected.

The list of functions can be completed according to your needs.

2.3 The labels to translate

When TraducTeurk has finished its first task, all the labels to translate are stored on this worksheet (in column B), sorted by module (column A). The translations that came across in the existing catalog files are added to the rightmost columns; the language of these labels are set in the headers of the columns.

During the browsing of the catalog files, if TraducTeurk runs into a translation that stands for a label that exists no longer in the module, it adds a line at the bottom of the list, on a red background.

In the example above, a PHP function using the label "Style" formerly declared in module Zenpa has been moved to module Kom1. Therefore we can see that the label "Style" has no translation yet in module Kom1 while the translation into en_US : "Style" has no reason left to exist.

2.4 The scanned folder tree

No real need for this sheet... it can sometimes help to have the list of his project files in Excel !

2.5 The analysed code

Mainly for debugging reasons, TraducTeurk writes the analysed code on this worksheet. The character strings detected as labels to translate are set on blue background. The associated module is put as comment of the cell.

Please be aware that TraducTeurk, which is a little bit uncouth, only takes account of the arguments that are present on the same line than the function... Avoid the line feeds !

3 Instruction for use

Basic : You only need to fill in the input and output folders and to follow the steps that are listed on the command worksheet.

4 The catalogs

The catalogs are generated in the output folder declared on the command worksheet. The thing left to do is to move or copy each catalog file in the _lang folder of its module.

5 How to get TraducTeurk ?

ToolOscope proposes to you a Shareware License :

You would like to try TraducTeurk : Register and download the software in full version for free. You are granted an evaluation license.
"What's the need ?" : Remove from your work spaces all your copies of the software and all by-products generated by it.
"This software is not bad, but..." : Ask for an evolution or a correction and describe precisely your needs.
"It works and I will keep on using it or its by-products" : Send your greetings to its creator.

For all this, please go to the User Space.