Yii 1.1: gemi

Language Selector, CRUD for languages and hardcoded strings translation / customization
8 followers

GeMI

Gestor de Múltiples Idiomas (Multiple Language Manager)


Presentation

This module provides:

  • Language Selector
  • CRUD for Languages (Idiomas model). NOTE: Delete operation is a soft delete.
  • Collects hardcoded strings written with Yii:t(), store them in a table allowing later translation.

ADDED: 2012-12-03 For non Spanish spoken people benefit; methods, properties and functions can be used in English language too. (italic form)

ADDED: 2013-01-02 There is no need to "force" to an inexistant language. Yii provides a function to "force" the translation (See Installation) The adventage of this change is enable a complete i18n implementation. sourceLanguage parameter backs to its original use, and language parameter still is dynamic, idiomaAux (langAux) is a new parameter to set the "auxiliar" language to use before to set sourceLanguage to translate. Example: Language XX is not defined or active, then GeMI ask for "idiomaAux" (langAux) and if it isn't active, sourceLanguage will be used. language is dynamic, because is the language odf the browser, and it can be changed by the user if the language selector is showed. sourceLanguage could be "es" and "idiomaAux" could be "en". When the tables are created, the language's table will have 2 records not soft deleted: "sourceLanguage" activado, and "idiomaAux" desactivado.

Important

Because the use of i18n lets use of any language, the database MUST have utf8 as character set and utf8_general_ci as collation. If the database isn't set in that way, the strings will have a wrong representation for languages like arabian, kanji, hebrew, etc... You can run this SQL statament to solve that: ALTER DATABASE mibbdd DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;


Installation

Copy 'gemi' folder inside 'modules'. Or well, Create a folder, named 'gemi', inside protected/modules and download inside the source code from repository.

Copy (or simlink) the file BeginRequest.php in the folder components. If there an existent file, adapt it to include provided source code.

If you have installed EUpdateDialog, this step is not needed: Copy (or simlink) the folder EUpdateDialog from modules/extensions to protected/extensions.

Edit config/main.php:

//Forces source language never exists
'sourceLanguage' => '¡¡',
'language' => 'es',

'import'=>array(
    'application.models.*',
    'application.modules.gemi.models.*',
 ),

// Associates the behavior class with onBeginRequest event.
// Set in the primary array affects to the whole application
// In this case, changes the selected language of the application
'behaviors' => array(
    'onBeginRequest' => array(
        'class' => 'application.components.BeginRequest'
    ),
),

'modules'=>array(
    ...
    'gemi'=>array(
        'mostrarTodos'=>true,     //showAll
        'mostrarInactivos'=>true, //showDeactivated
        'idiomaAux' => 'en',
    ), 

'messages' => array(
    'class' => 'CDbMessageSource',
    'sourceMessageTable' => 'tbl_msgOriginal',
    'translatedMessageTable' => 'tbl_msgTraducido',
    'onMissingTranslation' => array('MensajeATraducir', 'load'),
    'forceTranslation' => true, //Lets or not to modify the text "hard coded"
),

The tables are created "automagically".


Configuration

mostrarTodos: (showAll)

Lists All The Languages Defined Or Only The Activated Ones.
Possible Values:

  • true,
  • false,
  • a logic operation to be evaluated, i.e.:
"Yii::app()->user->checkAccess('Admin') || Yii::app()->user->checkAccess('UsuarioAvanzado')",
mostrarInactivos: (showDeactivated)

Lists All The Languages Not Soft Deleted.
For Instance, To Test The Transaltions Before Activate The Language Possible Values:

  • true,
  • false,
  • a logic operation to be evaluated, i.e.:
!Yii::app()->user->checkAccess('Admin')  && !Yii::app()->user->checkAccess('UsuarioAvanzado')

Implementation

Add to the desired menu this elements:

array('label' => Yii::t('int','Idiomas'), 'url' => array('/gemi/idioma/index')),
array('label' => Yii::t('int','Traducir'), 'url' => array('/gemi/msgTraducido/index')),

To use the Language Manager and the Message Translator, respectively.

All the strings to be translated MUST be

Yii::t('categoría', 'mensaje'[, número])

To show the language selector, i.e.:

In protected/views/layout/main.php

<div  id="language-selector" style="float:right; margin:5px;">
  <?php 
    eval(Yii::app()->getModule('gemi')->mostrarSelector);
  ?>
</div>

Notes

  • A Language is ACTIVE when the flag idiActivo is true
  • A Language is DEACTIVE when the flag idiActivo is false
  • A Language is AVAILABLE when the flag idiBaja is null
  • A Language is UNAVAILABLE when the flag idiBaja is DATETIME
  • At this moment, the language identification is ISO 639 (2 chars)
  • The field idiCodigo accepts 5 chars, as is indicated in ISO 3166-1 alfa-2 (es-ES, es-AR, etc) But will be considered the 2 first chars.
  • The language code MUST BE ALWAYS in lowercase.
  • If you want to allow only the users customization of the hardcoded strings, it is enough to not include the menu item gemi/idioma/index. At this moment this only applies to Spanish.

Available Functions

To use the functions provided you can do it in two ways:

$gemi = Yii::app()->getModule('gemi');
$gemi->function;

Or:

Yii::app()->getModule('gemi')->function;

mostrarTodos (showAll)

Type: Property
Value: true or false Explanation: Evaluates the parameter configured in main.php and returns true/false

mostrarInactivos (showDeactivated)

Type: Property
Value: true or false Explanation: Evaluates the parameter configured in main.php and returns true/false

mostrarSelector (showSelector)

Type: magic getter
Value: string
Explanation: Returns a string to be evaluated and renders a mini form with the language selector. This will be affected for the property mostrarTodos
Example:

eval(Yii::app()->getModule('gemi')->mostrarSelector);

Observations:
- It has its CSS style
- To Do: The CSS style can be customized or to be integrated to the CSS system file.

listarIdiomaCompleto (languageCompleteList)

Type: magic getter
Value: array
Explanation: Returns an array with all languages defined in the table, no matter if is soft deleted or no activated
Example:

$gemi = Yii::app()->getModule('gemi');
$listaIdiomasCompleto = $gemi->listarIdiomasCompleto;
print_r($listaIdiomasCompleto);

$listaIdiomaCompleto[array]:
    es => Español
    fr => François
    en => English

Observations:
- It's recommended native language for language name.
- To Do: It should return an array with the follow structure

$listaIdiomasCompleto[array]:
    es => Español, [active], [no soft deleted]
    fr => François, [active], [soft deleted]
    en => English, [no active], [no soft deleted]

listarIdiomasActivos (activeLanguageList)

Type: magic getter
Value: array
Explanation: Returns an array with all languages defined which flag active is true
Example:

$gemi = Yii::app()->getModule('gemi');
$listaIdiomasActivo = $gemi->listarIdiomasActivo;
print_r($listaIdiomasActivo);

$listaIdiomaActivo[array]:
    es => Español

Observations:
- It's recommended native language for language name.

listarIdiomasInActivos (deactiveLanguagesList)

Type: magic getter
Value: array
Explanation: Returns an array with all languages defined which flag active is false
Example:

$gemi = Yii::app()->getModule('gemi');
$listaIdiomasInActivos = $gemi->listarIdiomasInActivos;
print_r($listaIdiomasInActivos);

$listaIdiomaActivo[array]:
    en => English

Observations:
- It's recommended native language for language name.

listarIdiomasVigentes (*noSoftDeletedLanguagesList *)

Type: magic getter
Value: array
Explanation: Returns an array with all languages defined wich flag soft deleted is null
Example:

$gemi = Yii::app()->getModule('gemi');
$listaIdiomasVigentes = $gemi->listarIdiomasVigentes;
print_r($listaIdiomasVigentes);

$listaIdiomaActivo[array]:
    es => Español
    en => English

Observations:
- It's recommended native language for language name.
- To Do: It should return an array with the follow structure:

$listaIdiomasVigentes[array]:
    es => Español, [active]
    en => English, [no active]

listarIdiomasNoVigentes (softDeletedLanguagesList)

Type: magic getter
Value: array
Explanation: Returns an array with all languages defined which flag soft deleted is DATETIME
Example:

$gemi = Yii::app()->getModule('gemi');
$listaIdiomasNoVigente = $gemi->listarIdiomasNoVigente;
print_r($listaIdiomasNoVigente);

$listaIdiomaNoVigentes[array]:
    fr => François

Observations:
- It's recommended native language for language name.
- To Do: It should return an array with the follow structure:

$listaIdiomasNoVigentes[array]:
    fr => François, [active] //fr was activated but it was soft deleted

ListarIdiomasPersonalizado($sSQL) (CustomLanguagesList)

Type: Función
Parameter: $sSQL Value: array
Explanation: Returns an array with all languages which criteria where $sSQL
Example:

$gemi = Yii::app()->getModule('gemi');
$ListarIdiomasPersonalizado = $gemi->ListarIdiomasPersonalizado('idiActivo = 0');
print_r($ListarIdiomasPersonalizado);

$ListarIdiomasPersonalizado[array]:
    en => English

Observations:
- It's recommended native language for language name.
- To Do: It should return an array with the follow structure:

$ListarIdiomasPersonalizados[array]:
    en => English, [active], [no soft deleted]

idiomaPorDefecto (DefaultLanguage)

Type: magic getter
Value: string
Explanation: Returns a string with the default language
Example:

$gemi = Yii::app()->getModule('gemi');
$idiomaPorDefecto = $gemi->idiomaPorDefecto;
print_r($idiomaPorDefecto);

$idiomaPorDefecto[string]: es

Observations:
- To Do: It should be customized the default language in the table.

IdiomaEstaDisponible($sCodigoDeIdioma) (LanguageIsAvailable)

Type: Function
Parameter: $sLanguageCode Value: True/False
Explanation: Returns a true/false if the language is active or not, and it is not soft deleted
Example:

$gemi = Yii::app()->getModule('gemi');
$IdiomaDisponible = $gemi->IdiomaEstaDisponible('es');
$IdiomaNoDisponible = $gemi->IdiomaEstaDisponible('en');
$IdiomaNoDisponible2 = $gemi->IdiomaEstaDisponible('es');

print_r($IdiomaDisponible);
$IdiomaDisponible[bool]: true

print_r($IdiomaNoDisponible);
$IdiomaDisponible[bool]: false

print_r($IdiomaNoDisponible2);
$IdiomaDisponible2[bool]: false

Credits

These resources were used to develop this module:


Discussion

Total 3 comments

#10921 report it
DG Esteban A. Pérez at 2012/12/03 10:39am
Updated Names

Now methods, functions and properties can be used in English or Spanish

#10912 report it
DG Esteban A. Pérez at 2012/12/02 04:53pm
@guaruja

Si, desde un punto de vista "formal" es totalmente cierto.
Pero tuve en mente crearlo para los hispanoparlantes que "debemos" lidiar con el "inglés".
No descarto "i18n'ar" este módulo. De hecho, esta semana lo modificaré para que las funciones, propiedades y métodos también puedan usarse en inglés.
No voy a colaborar con la brecha idiomática, al contrario quiero ayudar a estrecharla.
Quizá lo veas como una pérdida de tiempo. Yo lo pienso desde otro lugar.
Gracias por tu participación. :)

#10907 report it
guaruja at 2012/12/02 07:41am
Method naming

If you are publishing your work as an extensions for others to use (which, no doubt, is a nice thing to do) you really should consider using method and variables names in english. Although (by coincidence) I understand your method names I never would use your extension in this condition. Besides messing up the source code with a mix of languages, the source code gets hard to be read by others that do not know this specific language. Imagine every russian, greek, indian, german, chinese ... developer starts naming variables and methods in their own language. Think of source code you will get after integrating some extension and you will get my point.

Leave a comment

Please to leave your comment.

Create extension
Downloads