Gestão dos plurais com o framework PHP Yii

Yii (para Yes, it is) é um framework PHP open-source e gratuito iniciado pelo Qiang Xue em 2008. Centrado no desempenho, baseado numa arquitetura MVC e seguindo o paradigma de programação orientada a eventos, também oferece a tradução de mensagens, a formatação de data e hora, os diferentes formatos de números e a localização de interface. Vamo-nos concentrar aqui sobre como Yii gerencia os plurais na função de tradução das mensagens da sua versão atual (1.1.13).

A internationalização com Yii

Vamos fazer uma implementação mínima do framework Yii que vai contar apenas com um controlador e um único método.

A internationalização dos textos em Yii pode-se fazer a partir de várias fontes:

• um array associativo de chaves/valores num conjunto de diretórios: esta é a opção padrão que utiliza a classe CPhpMessageSource
• uma base de dados contendo uma tabela fonte e uma tabela mensagem: esta solução utiliza a classe CDbMessageSource
• uma fonte GNU Gettext baseada em arquivos .po ou as parelhas binárias .mo deles: esta solução é definida pela classe CGettextMessageSource

Cada um destes métodos pode usar cachingDuration, um parâmetro que armazenará o resultado da tradução durante o tempo indicado.

No nosso exemplo, nós usamos um array associativo PHP.

A arquitetura dos arquivos será a seguinte:

framework/
test/protected/controllers/SiteController.php
test/protected/messages/pt/test.php
test/index.php

Para exibir corretamente os caracteres acentuados codificados em UTF-8, o arquivo de idioma protected/messages/pt/test.php deve, naturalmente, ser codificado em UTF-8, e o arquivo índice de sua aplicação (test/index.php) indica a codificação de caracteres com a linha seguinte:

header("Content-Type: text/html; charset=utf-8");

O arquivo test/protected/messages/pt/test.php contém o array associativo das chaves de tradução no idioma fonte (o inglês por defeito) e dos seus valores traduzidos.

return array (
    'You have a message.' => 'Você tem uma mensagem.',
);

No controlador, começamos por indicar a linguagem de consulta (aqui, o português), em seguida, usamos o método t da classe YiiBase (definida em YiiBase.php) que toma como parâmetros a categoria de mensagem (aqui, o nome do arquivo que contém o array associativo em messages/pt/, ou seja test), em seguida, a chave (ou a cadeia no idioma de origem).

echo Yii::t('test','You have a message.')

Obtemos bem: Você tem uma mensagem.

A pluralização com Yii

Voltemos ao nosso problema de pluralização de mensagem apresentado num post anterior (Uns plurais bem singulares). Lembremo-nos que existem dependendo das línguas diferentes formas de números gramaticais, e não somente um singular e um plural como em português.

Nosso exemplo, uma interface pode apresentar 0 mensagem (ou Nenhuma mensagem), 1 mensagem (ou Uma mensagem), ou ainda n mensagens, n sindo um espaço reservado para ser substituido durante o processamento.

O helper CChoiceFormat (que encontramos no diretório framework/i18n/) permite simplesmente expressar os diferentes valores possíveis de uma mensagem com as regras de pluralização das línguas já suportadas pelo framework, que encontramos no diretório framework/i18n/data/, nos arquivos dedicados a cada língua e locale.

Encontramos por exemplo às do português em pt.php:

'pluralRules' =>
    array (
        0 => '(n>=0&&n<=2)&&n!=2',
        1 => 'true',
    ),

É a classe CLocale quem acessa a isto através do seu método getPluralRules(). Este método é chamado pelo método t (utilizado acima) da classe YiiBase e do qual pode apreciar o código.

Para mais informações sobre os tipos de plurais por idioma, refiro-me ao Common Locale Data Repository do Unicode. Encontramos là explicitadas as régras de pluralização que permitem estabelecer as fórmulas acima referidas.

A compacidade de utilização destas regras é ilustrada aqui com uma palavra.

for ($i=0; $i<3; $i++)
{
    echo Yii::t('test', "mensagem|mensagens", $i);
}

Mostra com os valores de 0 até 2:

mensagem
mensagem
mensagens

Mas uma expressão mais significativa também pode ser usada.

for ($i=0; $i<4; $i++)
{
    echo Yii::t('test', "Você tem {n} mensagem.|Você tem {n} mensagens.", $i);
}

Mostra:

Você tem 0 mensagem.
Você tem 1 mensagem.
Você tem 2 mensagens.
Você tem 3 mensagens.

Também é possível refinar as mensagens usando diretamente uma expressão PHP ou um valor.

for ($i=0; $i<3; $i++)
{
    echo Yii::t('test', "0#Você não tem nenhuma mensagem.|1#Você tem uma mensagem.|n>1#Você tem algumas mensagens.", $i);
}

Mostra:

Você não tem nenhuma mensagem.
Você tem uma mensagem.
Você tem algumas mensagens.

Internationalização e pluralização

O próximo passo é, naturalmente, gerir ao mesmo tempo a internationalização e a pluralização. Para fazer isto, é só usar a mensagem completa com as variações de expressões no idioma fonte (aqui, o inglês) e usá-lo como chave no array das línguas.

Com um arquivo de linguagem como este:

return array (
 "0#You don't have any message.|1#You have one message.|n>1#You have many messages." => "0#Você não tem nenhuma mensagem.|1#Você tem uma mensagem.|n>1#Você tem algumas mensagens.",
);

O controlador:

for ($i=0; $i<3; $i++)
{
    echo Yii::t('test', "0#You don't have any message.|1#You have one message.|n>1#You have many messages.", $i);
}

Ainda mostra em português:

Você não tem nenhuma mensagem.
Você tem uma mensagem.
Você tem algumas mensagens.

E em inglês (comentando a linha Yii::app()->setLanguage('pt');) :

You don't have any message.
You have one message.
You have many messages.

As últimas palavras

Como pode ver a partir destes poucos exemplos, os desenvolvedores do framework Yii foram capazes de implementar uma solução muito elegante para a gestão dos plurais permitindo expressar uma grande complexidade devida à variedade de casos possíveis mantendo ao mesmo tempo uma facilidade relativa de utilização. Cobre uma parte dos diferentes tipos de plurais entre línguas com números gramaticais diferentes, e também permite gerenciar facilmente diferentes displays contextuais para a mesma língua.

Livros

Para ir mais longe no conhecimento do framework Yii, recomendo a leitura destes dois livros:

Yii Rapid Application Development, por Lauren J. O'Meara e James R. Hamilton III (2012, 340 páginas)

Vai descobrir neste livro o desenvolvimento de uma aplicação completa sob a forma de projetos e missões focados em características e pontos-chave do framework e de uma aplicação real.

Web Application Development with Yii and PHP, por Jeffrey Winesett (2012, 332 páginas)

Vai encontrar neste livro uma introdução ao framework, mas especialmente o desenvolvimento passo a passo de uma aplicação web completa.

Crédito da foto: gringer

Gestion des pluriels avec le framework PHP Yii (em francês)
Handling plurals with the Yii PHP framework (em inglês)
Gestión de los plurales con el framework PHP Yii (em espanhol)