Internacionalizar os templates

Porque criar templates multilíngues?

Assim que os documentos são colocados online, o SPIP adapta certas informações «automaticas» ao idioma desejado. Particularmente as datas são exibidas no idioma do site, ou de uma matéria, ou de uma seção, os formulários são exibidos no idioma correspondente (por exemplo, a interface para postar mensagens em fóruns)... Tudo isso já está traduzido pelo SPIP.

Porém, isso não é suficiente: os webmasters inserem nos seus templates um certo número de informações, descrevendo em particular os princípios de navegação no site. É preciso, por exemplo, exibir textos como «Mapa do site», «Responder a esta matéria», «Matérias do mesmo autor», «Na mesma seção»... Para um site em um único idioma, estes diferentes elementos são fáceis de inserir: colocam-se tal como estão no código HTML dos templates. O problema aparece quando o site é multilíngue: numa matéria em francês, queremos exibir «Répondre à cet article», mas numa matéria em inglês, precisamos de um texto diferente («Comment on this article»).

O SPIP oferece dois métodos para gerir estes elementos de texto diferentes conforme o idioma#:

— (1) um método consiste em armazenar os elementos de texto dos templates em ficheiros de idioma (um ficheiro diferente para cada idioma usado no site), separados dos templates; um template único (por exemplo article.html chamando, segundo os códigos definidos pelo webmaster, esses elementos de texto em função do idioma usado; deste modo, um mesmo template article.html exibirá automaticamente o texto «Répondre à cet article» ou «Comment on this document» em função do idioma da matéria. Este método é vivamente aconselhado, pois oferece a maior flexibilidade, facilita as atualizações do site (trabalha-se num template único que gere automaticamente diversos idiomas) e, eventualmente, ferramentas serão incluídas no SPIP para facilitar o trabalho coletivo de tradução da intercafe do seu site (diversos administradores, cada um falando um idioma diferente, poderão traduzir a interface de um mesmo site a partir da área restrita, sem ser preciso intervir nos ficheiros dos templates);

Cada string que precisar ser traduzida de acordo com o idioma é identificada por uma string de idioma, por exemplo, bouton_ajouter. Cada ficheiro de idioma define todas as traduções das strings de idioma para um dado idioma. Os templates podem, em seguida, usar uma string de idioma no meio da sintaxe básica <:bouton_ajouter:>.

É possível:
-  definir módulos de strings de idiomas. Originalmente, o núcleo do SPIP oferece 3: public, ecrire, spip;
-  definir strings de idiomas parametrados por argumentos, e passar valores para esses argumentos ao chamar a string num template;
-  aplicar filtros às strings de idiomas (nos templates), e passar argumentos a esses filtros.

A seção « Elementos linguísticos » (em programmer.spip.net) detalha esses elementos e, em particular, a sintaxe avançada das strings de idioma.

— (2) u,m método mais rapidamente acessível, tecnicamente muito simples, baseia-se na criação de ficheiros de templates diferentes para cada idioma. Neste método, constroi-se um ficheiro article.html para gerir as matérias em francês, e um ficheiro article.en.html para as matérias em inglês (note: article.html na realidade gere todos os idiomas excepto inglês). Este método é desaconselhado se o site usar numerosos idiomas e/ou se usar templates distintos de acordo com as secões. Além disso, em todo o caso, é vantajosamente substituído pelo método 3, descrito abaixo:

— (3) o método dos «blocos multilíngues», funciona igualmente bem nos conteúdos como nos templates. Basta inserir nos templates a estrutura abaixo:

<multi>
[fr] Répondre à cet article
[en] Comment on this article
</multi>

e a frase será exibida no idioma pretendido [1]. Embora este sistema seja muito flexível, atinge o seu limite quando o número de idiomas é grande, e diferentes tradutores precisem intervir no site (com efeto, é preciso que eles possam modificar o template, o que o método dos ficheiros de idiomas permite evitar).
Portanto é melhor adotar o método descrito abaixo.

1. Método dos ficheiros de idioma

O princípio dos ficheiros de idioma consiste em inserir num template único um código, que corresponderá, em cada idioma, a um elemento de texto (uma «string»); o código não varia entre os diferentes idiomas, mas o texto é traduzido.

Por exemplo, pode-se decidir que o código telechargement corresponde:
— em francês, à string «télécharger ce fichier»,
— em inglês, à string «download this file»,
— em espanhol, à cadeia «descargar este archivo»,
— em português, à cadeia «descarregar este ficheiro»
— etc.

No ficheiro de template das matérias (um único ficheiro gerirá todos os idiomas), article.html, basta inserir o código (note a sintaxe) : <:telechargement:>

Na exibição de uma matéria, este código será substituído pela sua tradução no idioma da matéria.

Por exemplo, no template article.html, inserimos no loop que exibe os documentos vinculados à matéria, o código a seguir:
<a href="#URL_DOCUMENT"><:telechargement:></a>

Se a matéria em questão for em francês, produzirá:
<a href="/IMG/jpg/meudocumento.jpg">télécharger ce fichier</a>

se a matéria for em inglês:
<a href="/IMG/jpg/meudocumento.jpg">download this file</a>

e assim sucessivamente. Um único template, contendo um único código, exibe um texto traduzidoem todos os idiomas usados no site

Usar os textos já traduzidos

Para facilitar o trabalho dos webmasters, o SPIP fornece um conjunto de strings já traduzidas (pelos tradutores do SPIP). Ao usar estas strings, correspopndentes a elementos de texto usados frequentemente em websites, o webmaster pode rapidamente realizar uma interface que funciona em vários idiomas, mesmo aqueles que ele não fala.

Exemplo: um webmaster quer realizar a interface para um site em português, em espanhol e em árabe, mas ele não fala espanhol e árabe. Ao inserir nos seus templates os códigos fornecidos pelo SPIP, não precisa se preocupar em obter as traduções para espanhol e árabe, já que o trabalho de tradução já foi realizado pelos tradutores do SPIP. Assim, ao completar a interface em português com os códigos fornecidos pelo SPIP, ele sabe que as suas páginas serão imediatamente exibidas em espanhol e árabe.

Se em seguida forem incluídas matérias em polaco, as páginas serão imediatamente exibidas com os elementos de texto traduzidos em polaco, sem que o webmaster precise intervir novamente.

Outra vantagem deste método: ele facilita a criação de templates «para distribuição» imediatamente multilíngues. Os templates realizados com este método serão imediatamente usáveis em todos os idiomas em que o SPIP estiver traduzido.

Do ponto de vista técnico, os elementos de texto fornecidos por padrão pelo SPIP são armazenados nos ficheiros de idioma do diretório «ecrire/lang/»:
— /ecrire/lang/public_fr.php, /ecrire/lang/ecrire_fr.php, /ecrire/lang/spip_fr.php, contêm as strings em francês,
— /ecrire/lang/public_en.php, /ecrire/lang/ecrire_en.php, /ecrire/lang/spip_en.php em inglês
— etc.

-  Criar os seus próprios códigos

Além disso, é possível criar os seus próprios códigos, correspondendo às strings que se deseja adicionar.

Isto envolve a criação de ficheiros de idioma pessoais, no modelo dos ficheiros public_xx.php. Para criar os seus próprios ficheiros, grave num diretório squelettes/lang (a ser criado, caso não exista)
— local_fr.php para definir as strings em francês,
— local_en.php em inglês,
— ...

Por exemplo, podem ser criadas as strings a seguir:
— telechargement para exibir «Descarregar a versão mais recente»,
— quoideneuf para exibir «Modificações recentes».

De acordo com este método, insere-se nos templates os códigos <:telechargement:> e <:quoideneuf:> e eles serão exibidos com as traduções correspopndentes, tal como definidas nos ficheiros local_xx.php. Par uma utilização avançada, é posível incluir variáveis <:quoideneuf:{fichier=cabecadevento.txt}:>(consultar a documentação em->http://programmer.spip.org/Syntaxe-complete-des-codes-de])

Note que os códigos são arbitrários: é você que os escolhe. Recomendamos evidentemente que escolha códigos fáceis de lembrar Notons que les codes sont arbitraires : c’est vous qui les choisissez. Nous recommandons bien évidemment de choisir des codes qui vous permettent de les retenir facilement (em vez de números, por exemplo).

Atenção: apenas letra «minúsculas» e «não acentuadas» («a» a «z»), números («0» a «9») e o sublinhado (underscore «_») são permitidos nos nomes das chaves. Assim 'telechargement' => 'Téléchargez votre fichier.' funcionará corretamente, porém nem 'Telechargement' => 'Téléchargez votre fichier.', nem 'téléchargement' => 'Téléchargez votre fichier.' serão funcionais.

Evoluções

Depois da versão 3.0 do SPIP, esta funcionalidade foi amplamente revista e melhorada.

• a substituição por local_xx.php foi mantida;
• a substituição de um módulo de idioma pode conter unicamente os códigos de idioma a serem alterados.

Assim, um template ou um plugin pode visar um ou mais códigos de idioma a substituir sem precisar conter o conjunto completo de códigos de idioma do módulo que substitui.

Ordem das substituições :
As substituições ocorrem sucessivamente na ordem inversa do «path» :

1. ecrire/lang/ [pode ser substituído por...]
2. prive/lang/ [pode ser substituído por…]
3. squelettes-dist/lang/ [pode ser substituído por…]
4. plugin_A/lang/ [pode ser substituído por…]
5. plugin_B/lang/ dependendo do plugin A [pode ser substituído por…]
6. squelettes/lang/

Um plugin_B pode substituir um ou mais códigos de idioma de um plugin_A, se B for dependente de A.
Os ficheiros de idiomas em «squelettes/lang/» substituem todos os outros.

Importante :
É indispensável, ao escrever os seus templates que o item de idioma seja precedido pelo prefixo do plugin do qual ele depende: por exemplo, uma string de idioma traduzida num ficheiro de idioma do plugin «meu_plugin» deverá ser chamada nos templates por: <:meu_plugin:minha_traducao:>.

Exemplo concreto:
«plugins-dist/forum/lang/forum_fr.php» contém o elemento:
'form_pet_message_commentaire' => 'Un message, un commentaire ?',
«plugins-dist/petitions/lang/petitions_fr.php» contient l’élément :
'form_pet_message_commentaire' => 'Un message, un commentaire ?',

Para substituir as duas strings de idiomas pela mesma tradução, basta incluir no template «squelettes/lang/local_fr.php» 'form_pet_message_commentaire' => 'ma traduction personnalisée',
Para substituir unicamente a tradução para petições, basta incluir em «squelettes/lang/petitions_fr.php»
'form_pet_message_commentaire' => 'ma traduction personnalisée pour pétitions uniquement',
Os outros códigos de idioma contidos no plugin petições serão considerados e apenas esta tradução será modificada.

Este funcionamento é válido para todos os módulos de idiomas, tantos dos plugins como do núcleo.

Técnica

Os ficheiros de idiomas contêm as diferentes traduções dos códigos que você utilizará; são ficheiros PHP que contêm uma matriz associando aos códigos as strings correspondentes em cada idioma.

Atenção :
O nome desses ficheiros de idioma não deverá conter o caracter «_» («underscore» ou «sublinhado») excepto para marcar a separação com a sigla do idioma (pt, en, fr, it...). Por exemplo, deve ser «meuidioma_pt.php» e não «meu_idioma_pt.php».

Esses ficheiros conterão, por exemplo:

Versão francesa (lang/meuidioma_fr.php):

  <?php
  $GLOBALS[$GLOBALS['idx_lang']] = array(
    'telechargement' => 'Télécharger la dernière version',
    'quoideneuf' => 'Modifications récentes'
  );
  ?>

Versão catalã (lang/meuidioma_ca.php) :

  <?php
  $GLOBALS[$GLOBALS['idx_lang']] = array(
    'telechargement' => 'Descarregar la darrera versió',
    'quoideneuf' => 'Modificacions recents'
  );
  ?>
  

A construção é a seguinte:

• no começo do ficheiro:

  <?php
  $GLOBALS[$GLOBALS['idx_lang']] = array(

• no fim do ficheiro:

  );

• a parte que precisa ser enriquecida, propriamente dita, consiste de várias linhas de definições, no modelo:

    'codigo' => 'a string a exibir',

Nota
— Cada linha de definição termina por uma vírgula, excepto a última linha.
— Os apóstrofos dentro da string devem ser escapados, ou seja, precedidos por uma barra invertida. Por exemploe, a string «sur l’internet» deve ser escrita como: sur l\'internet.

2. Templates separados para cada idioma

Atenção Este segundo método requer o plugin "Squelettes par rubriques", que é fornecido com o SPIP até a versão SPIP3.2. A partir do SPIP 4, o template não está mais incluído na distribuição padrão e precisa ser instalado via SVP. (ver https://plugins.spip.net/squelettes...)

Esta abordagem, mais acessível aos webmasters menos experientes, consiste na criação de templates diferentes para cada idioma Um pouco sobre o mesmo princípio que consiste em criar templates específicos para diferentes seções para obter interfaces gráficas diferentes.

Queremos criar um site em português (idioma padrão), inglês e espanhol. Criámos três ficheiros de template diferentes:
— article.html para português (na realidade, para todos os idiomas que não possuam ficheiro de idioma específicado a seguir),
— article.en.html pour l’anglais,
— article.es.html pour l’espagnol.

(Nota: se publicarmos uma matéria em alemão, enquanto não existir um esqueleto article.de.html no nosso site, será utilizado o esqueleto article.html.)

Importante: para que os templates «por idioma», definidos pela inclusão de .lang após o nome, soient pris en compte, é obrigatório que exista a versão «padrão» no site.

Aqui, se article. html não existir (teríamos preferido nomear diretamente article.pt.html), os ficheiros em inglês e espanhol não serão tidos em conta.

Isto pode ser combinado com a nomenclatura "por seção", também fornecida pelo plugin "Squelettes par rubrique".
Quando os seus templates combinam a segregação por idioma e por secção, é tida em conta a seguinte ordem:
— article=8.es.html (o template para as matérias em espanhol da seção 8, mas não as suas subseções),
— article=8.html (o template para as matérias da seção 8, mas não as suas subseções),
— article-2.es.html (o template para as matérias em espanhol da seção 2, e as suas subseções),
— article-2.html (o template para as matérias da seção 2, e as suas subseções),
— article.es.html (o template para as matérias em espanhol),
— article.html (o template para as matérias),
— article-dist.html (o template para as matérias fornecido pelo SPIP).

Note: Salvo algumas exceções, os códigos de idioma de duas letras normalizados pela ISO, como "es", devem ser utilizados aqui. A lista pode ser consultada no site da Biblioteca do Congresso dos Estados Unidos (sim!).

Para garantir a máxima compatibilidade, os códigos ISO de duas letras ("iso 639-1") devem ser utilizados prioritariamente, quando existem, e para uma designação mais especializada de um idioma dentro da sua família linguística, os códigos ISO de três letras ("iso 639-2 T"). Por exemplo, o alemão será designado por "de". Mas a ISO apenas tem em conta 182 dos 5.000 a 7.000 idiomas falados no mundo; para idiomas ainda não listados, pode-se inspirar no diretório proposto pelo site ethnologue.com; para saber mais, aceda à lista spip-trad.

Facilite a sua vida. Um dos métodos de estruturação muito simples que o SPIP permite para gerir um site multilingue consiste em associar diretamente os idiomas às seções (e não matéria a matéria). Assim, no caso em que as matérias no mesmo idioma são agrupadas na mesma seção (ou mesmo por setor), podemos simplesmente criar os templates específicos por seção, sem utilizar os nomes dos ficheiros por idioma.

Desta forma, se todas as matérias em espanhol forem agrupadas na seção 8 (e nas suas subseções), podemos simplesmente nomear o ficheiro adaptado ao espanhol rubrique-8.html em vez de rubrique.es.html.

Podemos imaginar os problemas que podem surgir com este método:
— o ficheiro article-2.html precisa existir se quisermos que article-2.es.html seja selecionado;
— não é possível decidir, ao contrário, que article.es.html deve ser usado no lugar de ’article-2.html se o article-2.es.html não existir: a seleção por seções tem sempre prioridade sobre a seleção por idiomas;
— uma correção de layout num template implica em se fazer a mesma correção nas outras versões,
— deve ser possível inserir elementos de texto à vontade nos ficheiros de esqueleto, mesmo que não entendamos necessariamente o idioma (imagine criar templates em árabe quando só se fala o seu idioma nativo...).

Este método destina-se a trabalhar rapidamente em sites pouco complexos (poucos - ou nenhum - templates específicos das seções) e/ou usando poucos idiomas diferentes. a partir do momento em que o seu projeto multilíngue se torne um pouco mais ambicioso, é fortemente aconselhável adotar o método de ficheiros de idioma.

3. Os blocos multilíngues

Os blocos multi, definidos na matéria
Les blocs multi définis dans l’article Criar um site multilíngue funcionam igualmente bem dentro dos textos dos autores ou palavras-chave como nos templates. Atenção, esses blocos apenas gerem texto, e não os loops do SPIP!

Para gerir rapidamente um site multilíngue, este é, sem dúvida, num primeiro momento, o melhor método, ao mesmo tempo acessível e eficaz; em seguida, uma vez o seu site estabilizado, se precisar refinar os seus templates (por exemplo, para abrí-los a mais idiomas; ou para distribuí-los na forma de contribuição; ou ainda para os «profissionalizar»), será preciso transformar os seus blocos em ficheiros de idioma.