Página Inicial

Tradução do CACIC

O CACIC vem sendo usado cada vez mais e para atender às necessidades de comunidades que não têm o português (brasileiro) como primeiro idioma é necessário traduzí-lo.

Alguns esforços são (ou já foram) empreendidos para nacionalizá-lo (ex: espanhol) onde recursos foram disponibilizados para traduzir as mensagens/textos. Porém, tais esforços não refletiram em melhoria no código do CACIC, pois, as alterações foram realizadas no próprio código.

Para que o CACIC possa ser usado alem-fronteira é necessário que haja um método adequado de internacionalização que facilite tanto para o desenvolvedor quanto para o tradutor. No fórum (Traduções - Comienzo de la traducao'') foram apresentadas idéias para para que o método a ser utilizado fosse debatido e a seguir está o método que está em franco desenvolvimento para a nova versão (2.4).

Observação: O foco principal da implementação de tradução para a versão 2.4 será o ambiente do gerente.

Gerente

O ambiente gerente do CACIC contém a maior parte das mensagens/texto a serem apresentados ao seu usuário, sendo então onde se tem maior necessidade de tradução. Desta forma, o uso do CACIC terá maior ambrangência de uso e podendo ter maior número de contribuidores.

Exemplo de telas traduzidas:

Menu esquerdo - inicial	Menu esquerdo - inicial após entrada

A tradução

O recurso de tradução do CACIC possui duas frentes, sendo uma para o desenvolvedor e outra para o tradutor. Uma classe php de tradução criada exclusivamente para isso está sendo usada (phpTranslator-0.2.0). Essa classe possibilita uma fácil interação por ambas as partes.

Interação do Desenvolvedor

Para que o desenvolvedor possa realizar a tradução é necessário alguns passos básicos de instanciação da classe (phpTranslator) para que esta possa ser usada. Esse passo já foi realizado, devendo todo programa que queira realizar tradução usar a biblioteca de funções gerais do CACIC (include/library.php).

O cabeçalho do programa que irá usar a tradução deverá conter:

<?php
...
require_once('caminho ./include/library.php');
...
?>

Feito isso, usando-se o objeto de tradução criado/instanciado ($oTranslator), o uso poderá ser realizado para cada mensagem/texto a ser apresentado ao usuário.

Exemplo de uso:

• HTML original

  <table cellspacing=0 cellpadding=0 border=0 cols=6 width=100%>
    <tr nowrap>
       <td nowrap><a href="principal.php" target="mainFrame" title=""><b>Página Principal<b></a></td>
    </tr>
       <tr nowrap>
       <td nowrap><a href="/menu_esq.php?p=1|&v_no=1#1"><img src="imgs/arvore/tree_expand.gif" border=no></a></td>
       <td nowrap colspan=2><a href="/menu_esq.php?p=1|&v_no=1#1"><b>Computadores</b></a></td>
    </tr>
    <tr nowrap>
       <td nowrap><a href="/menu_esq.php?p=4|&v_no=4#4"><img src="imgs/arvore/tree_expand.gif" border=no></a></td>
       <td nowrap colspan=2><a href="/menu_esq.php?p=4|&v_no=4#4"><b>Relatórios</b></a></td>
    </tr>
    <tr nowrap>
       <td nowrap><a href="/menu_esq.php?p=12|&v_no=12#12"><b>Estatísticas</b></a></td>
    </tr>
    <tr nowrap>
       <td nowrap><a href="http://www.softwarepublico.gov.br/" target="new"><b>Comunidade CACIC<b></a></td>
    </tr>
  </table>
  

• HTML com uso do objeto ($oTranslator) de tradução
  • A mensagem/texto a ser apresentado deve ser substituído por código php de tradução.
  • O objeto de tradução possui o método getText e seu álias "_" (underscore) que devem ser usados com o parâmetro que informa o código da mensagem/texto a ser exibido.

Sintaxe:

<?php
$oTranslator->getText('código da mensagem'); 

ou

$oTranslator->_('código da mensagem'); 
?>

Onde: Código da mensagem = Código da mensagem a ser exibido no html

Exemplo:

<table cellspacing=0 cellpadding=0 border=0 cols=6 width=100%>
  <tr nowrap>
     <td nowrap><a href="principal.php" target="mainFrame" title=""><b><?php $oTranslator->_('kciq_msg homepage'); ?><b></a></td>
  </tr>
     <tr nowrap>
     <td nowrap><a href="/menu_esq.php?p=1|&v_no=1#1"><img src="imgs/arvore/tree_expand.gif" border=no></a></td>
     <td nowrap colspan=2><a href="/menu_esq.php?p=1|&v_no=1#1"><b><?php $oTranslator->_('kciq_msg project'); ?></b></a></td>
  </tr>
  <tr nowrap>
     <td nowrap><a href="/menu_esq.php?p=4|&v_no=4#4"><img src="imgs/arvore/tree_expand.gif" border=no></a></td>
     <td nowrap colspan=2><a href="/menu_esq.php?p=4|&v_no=4#4"><b><?php $oTranslator->_('kciq_msg community'); ?></b></a></td>
  </tr>
  <tr nowrap>
     <td nowrap><a href="/menu_esq.php?p=12|&v_no=12#12"><b><?php $oTranslator->_('kciq_msg user'); ?></b></a></td>
  </tr>
  <tr nowrap>
     <td nowrap><a href="http://www.softwarepublico.gov.br/" target="new"><b><?php $oTranslator->_('kciq_msg password'); ?><b></a></td>
  </tr>
</table>

Outros recursos do método getText

Para o método getText (ou seu alias _) poderão ser passados outros parâmetros além do código da mensagem. Veja seguir:

<?php
  /**
   * Busca o texto a ser traduzido
   *
   * Busca a traducao do texto - caso o texto traduzido nao exista retorna o texto padrao e caso este 
   * tambem nao exista retorna o codigo de pesquisa
   *
   * @access public
   * @param string $_msg_code O codigo da mensagem a ser traduzida
   * @param boolean $_sigla Se retorna a sigla em lugar da mensagem completa
   * @param boolean $_text_case Se o texto retorna o texto como cadastrado, em maiusculas ou minusculas
   *                                                1 - maiuscula
   *                                                2 - minuscula
   *                                            outro - como estiver cadastrado
   * @param array $_args Sao os argumentos que serão inseridos na mensagem nas posições onde houver %N 
   *                     (onde N é a quantidade sequencial de parâmetros)
   *
   * @return string  O texto traduzido, o texto padrao ou o codigo da mensagem
   *
   */ 
   getText( $_msg_code, $_sigla=false, $_text_case=0, $_args = array() )
?>

• O único parâmetro obrigatório é primeiro - o código da mensagem.
• Apenas os dados do quarto parâmetro (array) poderão ser passados fora de ordem.

Exemplo fictício para o array:

   mensagem = "O usuário %1 não tem autorização para o arquivo %2 na pasta %3.";

<?php
  // informações ao usuário
  $user_auth = array('Sálomé', 'CACIC-Manual do Administrador.pdf','doc/manuais');

  echo $oTranslator->_('mensagem', $user_auth); 
  // Retorna: O usuário Sálomé não tem autorização para o arquivo CACIC-Manual do Administrador.pdf na pasta doc/manuais.  

  echo $oTranslator->_('mensagem', false, $user_auth);
  // Retorna: O usuário Sálomé não tem autorização para o arquivo CACIC-Manual do Administrador.pdf na pasta doc/manuais.  

  echo $oTranslator->_('mensagem', false, 2, $user_auth);
  // Retorna: O USUÁRIO Sálomé NÃO TEM AUTORIZAÇÃO PARA O ARQUIVO CACIC-Manual do Administrador.pdf NA PASTA doc/manuais.  
?>

Criação dos arquivos de mensagens

Para que o desenvolvedor possa usar o objeto ($oTranslator) de tradução nas aplicações que implementar é necessário que ele também mantenha a base de dados de mensagens padrão. A base de dados é um arquivo texto (com formatação específica) que é gravado no sistema de arquivos do CACIC-gerente (language).

A manutenção desse arquivo de texto deverá ser realizada pela própria classe phpTranslator.

Amostra de tela de insersão de mensagens padrão:

Inclusão de mensagens padrão

Para ter acesso a esse recurso o desenvolvedor deverá copiar o arquivo admin/tradutor.php para admin/tradutor-devel.php. Deverá realizar a alteração no arquivo admin/tradutor-devel.php (~linha 96) conforme abaixo.

De:
<?php
   $oTranslator->translatorGUI();
?>

Para:
<?php
   $oTranslator->translatorGUI(false);
?>

Observação:

• Esse arquivo NÃO poderá ser incluído no controle de versão.
• Esse arquivo NÃO poderá ser incluído no menu do sistema.

Inserção de textos muito longos

A inclusão de textos muito longos (ex: textos de ajuda) poderá ser realizada usando um tipo de mensagem (campo do formulário - veja figura acima) especial. O tipo de mensagem é um campo livre, mas se preenchido com a palavra arquivo fornecerá à classe tradutora a informação que o campo mensagem conterá o nome do arquivo que deverá será usado na tradução.

Sintaxe:

Tipo da mensagem:	arquivo
Mensagem:	nome_do_arquivo.ext

Exemplos:

Tipo da mensagem:	arquivo
Mensagem:	introducao.html

Tipo da mensagem:	arquivo
Mensagem:	introduction.html

Nesse exemplo diz-se que o conteúdo dos arquivos introducao.html e introdution.html deverá ser usado como mensagem a ser apresentada ao usuário. Esses arquivos deverão ser criados por um editor externo e colocados no diretório language/pt-br/ e language/en-us/ (conforme o idioma).

---

Interação do Tradutor

A tradução é bem facilitada...

Tradução de mensagens padrão

A página de tradução listará todas as mensagens padrão colocando em destaque aquelas que ainda não estiverem traduzidas. Para realizar a tradução insira a texto e/ou a sigla e acione a opção salvar para manter a tradução para o idioma.

Criação de uma nova tradução

Por enquanto esse processo ainda não está automatizado, sendo a imagem acima para idiomas que já têm a tradução iniciada. Para iniciar uma tradução nova há a necessidade de criação manual (por enquanto ;) de alguns arquivos e diretórios... :P

Dentro do diretório language crie:

1. Arquivo que contem as definições do idioma. Para que possamos padronizar, o nome do arquivo deverá ser igual à respectiva sigla e deverá ser formatado como segue:
   • Sigla de duas letras do idioma (ISO-639-2) - em minúsculo - ex: en
   • Sigla de duas letras do país (ISO-3166-1) - em maiúsculo - ex: UK
   • Ambos devem estar unidos entre si pelo símbolo _ (underscore).

     en_UK.php
     
     <?php
       // Descricao do idioma - escrito como no país de origem.
       $language_def = 'English (UK)';
       // Sigla conforme padrão estabelecido.
       $language_abbr = 'en_UK';
       // Charset - conjunto de codificação de caracteres a ser usado
       $language_charset = 'iso-8859-1';
       // Direção de escrita
       $language_direction = '0'; // 0=esquerda para direita, 1=direita para esquerda
       // Versão da tradução
       $language_version = '0.1';
       // Versão do CACIC
       $language_cacic_version = '2.4.0';
     ?>
     
     

2. Criar pasta de mesmo nome e formato da sigla.
   • Seguindo o nosso exemplo: "en_UK"

     mkdir en_UK
     

3. Copiar todos os arquivos de menu do idioma padrão (pt_BR) para o diretório recém criado. Para traduzí-los edite-os em seu editor preferido e salve-os conforme o charset que foi definido.

   cp pt_BR/menu_* en_UK/
   

4. Para realizar a tradução das mensagens acesse o sistema CACIC como administrador e use a opção "Manutenção->Tradutor".

Observação: Os arquivos externos, criados pelo desenvolvedor, também deverão ser editados (por enquanto) externamente à aplicação.

---