PHP Coupé

Aprendendo

Trabalhando com diomas

A partir de sua versão 0.4 o PHP Coupé ganhou a capacidade de traduzir os projetos para outros idiomas com extrema facilidade. O único trabalho que se deve ter é realmente traduzir as páginas, pois o esquema de gerenciar os documentos e idiomas está pronto e pode ser utilizado de duas maneiras diferentes: (1) a tradução de documentos inteiros e (2) a tradução de string. Veja como utilizar ambas:

Configurando os idiomas

Antes de usar o sistema de tradução da forma que achar melhor, é necessário configurarmos o PHP Coupé para dizer quais idiomas nosso site terá e qual desses idiomas é o padrão do site (aquele que é usado quando nenhum idioma foi escolhido).

Se você está lendo os textos da seção Aprendendo na ordem em que aparecem, já deve ter visto no link Como configurar como se configura os idiomas. Caso não tenha, vamos lá:

Como todas outras configurações do PHP Coupé , a configuração dos idiomas a serem utilizados ficam no arquivo 'config.inc.php' dentro de sua pasta 'manager'.

Dentro do arquivo de configuração procure por $config['IDIOM']. Nesse vetor informamos, através de um array, os idiomas que são usados em nosso site. Sendo que a chave associativa é o código do idioma no formato ISO639-2. E o conteúdo da posição leva o nome dos idiomas separados por vírgula. Essas informações serão usadas mais tarde para gerar o menu para escolha do idioma. Veja o exemplo:

$config['IDIOM'] = array(
'por' => 'Português,Inglês,Espanhol',
'eng' => 'Portuguese,English,Spanish',
'spa' => 'Portugués,Inglés,Español'
);

Na configuração acima dizemos que nosso site terá três idiomas: Português, Inglês e Espanhol.

Agora devemos ir logo abaixo no arquivo de configuração, em $config['IDIOM_DEFAULT'], e dizer quais dos idiomas citados é o idioma padrão do site. Aquele que é usado enquanto nenhum outro idioma é definido. No caso, vou escolher Português:

$config['IDIOM_DEFAULT'] = 'por';

Definidos os idiomas e o idioma padrão, estamos prontos para começar a traduzir nosso projeto!

Tradução de documentos

Como o próprio título sujere, ao invés de ficar traduzindo palavras ou frases, podemos traduzir documentos inteiros do nosso projeto.

Para isso, após configurados os idiomas no arquivo de configuração, basta criarmos dentro das pastas 'contents', 'modules', 'blocks' e 'templates', diretórios com o mesmo nome dos códigos que demos aos idiomas, exceto o idioma padrão. O idioma padrão não deve ter uma pasta criada pois seus documentos continuam na raiz. Somente os outros documentos devem ter uma pasta criada com o mesmo nome do seu código (no caso 'eng' e 'spa').

Na primeira tela os diretórios de recurso. Na segunda os diretórios de recursos agora com as pastas que armazenam os documentos traduzidos.

Agora basta copiar os domentos traduzidos para dentro de cada idioma correspondente e inserir a marcação {{translate}} aonde quizermos que o menu para troca de idiomas apareça.

Resumo:

1. Configure o arquivo 'config.inc.php' com os idiomas;
2. Crie diretórios com o mesmo nome dos códigos dentro das pastas de recurso (exceto o idioma padrão);
3. Traduza os documentos e coloque-os dentro da pasta do idioma correspondente;
4. Insira a marcação para gerar o menu de idiomas.

Tradução de strings

Se não for do seu interesse traduzir documentos completos (Conteúdos, Templates, Blocos ou Módulos), mas precisa traduzir alguns trechos do seu texto ou criar alertas de sistema em diferentes idiomas, podemos utilizar o sistema de tradução de uma segunda forma.

Para essa tarefa temos o diretório chamado manager/system/language. É nesse diretório que armazenaremos os trechos de códigos traduzidos. Da mesma forma que a tradução de documentos inteiros, devemos criar as pastas dos idiomas definidos exceto o idioma padrão. Os arquivos com as frases no idioma padrão ficam na raiz do diretório 'language'.

Feito isso podemos começar a criar nossos arquivos de tradução.

Os arquivos de tradução de string são arquivos PHP que definer as string dentro do vetor $lang[]. As traduções serão identificadas pela chave associativa que será criada ao definir uma nova string ao vetor. Como exemplo:

<?php

$lang['aviso_sucesso'] = 'Operação realizada com sucesso!';
$lang['alerta_arquivo'] = 'Arquivo não encontrado!';

?>

Agora basta inserir a marcação {{translate}} aonde quizermos que o menu para troca de idiomas apareça.

Na primeira tela a área demarcada indica o local onde foi inserida a marcação para inclusão do menu de idiomas. Na segunda tela se pode ver o menu em ação.

Resumo:

1. Configure o arquivo 'config.inc.php' com os idiomas desejados;
2. Crie diretórios com o mesmo nome dos códigos dentro das pastas language (exceto o idioma padrão);
3. Crie seus arquivos de tradução em formato PHP definindo suas traduções dentro do vetor $lang[];
4. Insira a marcação para gerar o menu de idiomas;
5. Importe a classe Coupé Translate para exibir suas traduções.

Customizando o menu de idiomas

Por padrão o PHP Coupé gera o menu para escolha de idiomas na forma de um formulário com um campo select e um botão que submete a escolha via POST. Porém é possível customizar esse menu gerando, ao invés de um formulário, uma lista ordenada onde os idiomas são definidos via GET através de links.

Na esquerda temos o menu para troca de idomas padrão. No lado direto temos o menu customiza em forma de lista utilizando o bloco phpcoupe_translate.blk.php e a palavra coringa %list%.

A custumização deve feita dentro de um Bloco de Conteúdo de nome reservado phpcoupe_translate.blk.php. Dentro desse bloco criamos nosso menu customizado utilizando-se de códigos HTML e as palavras "coringas". O nome desse bloco foi convencionado onde o prefixo 'phpcoupe_' indica que o bloco é para uso do sistema PHP Coupé , e o sufixo 'translate' diz respeito a qual função do sistema ele pertence.

Palavras coringas são marcações especiais que serão substituidas por algo dinâmico durante a execução do programa. No caso, as palavras coringas serão substituidas pela lista de idiomas indicados no arquivo de configuração para que não tenhamos que fazer isso manualmente. Seja como um select ou como uma lista. As palavras coringas que podemos usar são:

• %select% - Gera um select com os idiomas configurados
• %buttom% - Gera um botão para submeter o formulário onde está o select
• %list% - Gera uma lista ordenada com os idiomas configurados

Assim, caso queira usar o menu padrão gerando automáticamente pelo PHP Coupé , deixe o Bloco de Conteúdo phpcoupe_translate vazio ou simplesmente delete o arquivo. Mas se quiser customizar o que substituirá a marcação {{translate}}, edite o Bloco e insira seus códigos HTML e códigos coringa que fazem o trabalho de gerar o menu na forma de um formulário ou como uma lista.