Internacionalização PHP (i18n): guia prático para programadores

Leva o teu site PHP para o mundo: Uma solução de internacionalização mais eficiente

Se és como eu e manténs projetos PHP "puros", sem depender de grandes frameworks (como o Laravel ou o Symfony), então o suporte a vários idiomas (i18n) provavelmente já foi uma dor de cabeça recorrente, mesmo que pequena.

A solução tradicional, o gettext, apesar de poderosa, é bastante trabalhosa de configurar. Especialmente em projetos pequenos, parece que estamos a "usar um canhão para matar uma mosca". O que precisamos mesmo é de um método que se implemente rapidamente, sem complicar demasiado.

Depois de muita tentativa e erro em vários projetos, desenvolvemos uma solução leve de internacionalização baseada em ficheiros de arrays PHP e ferramentas de tradução online. Esta abordagem não só é simples de implementar, como também tem custos de manutenção extremamente baixos. Hoje, vou partilhar contigo toda esta solução, sem restrições.

Guia prático: Como consegui suporte multi-idioma em PHP com o O.Translator

A nossa ideia central é muito simples: Cada idioma corresponde a um ficheiro PHP, que contém um return com um array associativo. Este método é simples, intuitivo e tem um impacto mínimo na performance.

Passo 1: Planeia a Estrutura das Tuas Pastas

Uma estrutura de pastas clara já é meio caminho andado. Para manter tudo organizado, vamos colocar todos os ficheiros de idiomas na mesma pasta e nomeá-los com os códigos de idioma, assim:

project_root/
├── index.php         // Your main logic file
├── i18n/             // Folder for all language files
│   ├── lang.cn.php   // Chinese language pack
│   ├── lang.en.php   // English language pack
│   └── lang.fr.php   // French language pack

Passo 2: Cria o Teu "Arsenal de Idiomas"

A seguir, vamos criar o ficheiro base de idioma. Vamos usar o chinês como exemplo e criar um ficheiro lang.cn.php. O conteúdo do ficheiro é um array PHP simples, onde as chaves são identificadores únicos e os valores são as strings de texto correspondentes.

Exemplo de lang.cn.php: As chaves mantêm-se iguais, os valores mudam conforme o idioma

Passo 3: Entra no Feiticeiro das Traduções, o O.Translator

Traduzir manualmente dezenas ou centenas de entradas? Esse é exatamente o tipo de trabalho repetitivo que os programadores mais detestam. É aqui que entra a nossa arma secreta, o O.Translator.

É uma plataforma profissional de tradução de documentos online que suporta ficheiros PHP na perfeição, permitindo ler diretamente o teu array e traduzi-lo para mais de 70 idiomas.

O processo é absurdamente simples:

Visita a homepage do O.Translator e faz upload do teu ficheiro de idioma base (por exemplo, lang.cn.php).
Seleciona os idiomas de destino, como inglês e francês.
Clica em traduzir, espera um pouco, e os teus ficheiros traduzidos lang.en.php e lang.fr.php vão estar prontos para ti.

O que mais me impressionou foi que o O.Translator te permite pré-visualizar uma parte da tradução gratuitamente. Se estiveres satisfeito com o resultado, podes então decidir se queres pagar pela tradução completa. Nas palavras deles: "Nunca pagues por um produto com o qual não estejas satisfeito."

Passo 4: Dá vida ao código

Está tudo pronto; só falta o toque final. Agora, vamos modificar o ficheiro principal index.php para que possa carregar dinamicamente o pacote de idioma certo com base na seleção do utilizador.

<?php

// 1. Determine the current language (using a GET parameter for demonstration)
$supported_langs = ['en', 'cn', 'fr'];
$default_lang = 'en';
$lang = isset($_GET['lang']) && in_array($_GET['lang'], $supported_langs) ? $_GET['lang'] : $default_lang;

// 2. Load the corresponding language file
// Use a global variable like $_ or a specific variable like $TEXTS to store the strings
$_ = require_once __DIR__ . "/i18n/lang.{$lang}.php";

?>

No teu template HTML, podes então chamar facilmente as strings de texto assim:

<!DOCTYPE html>
<html lang="<?php echo htmlspecialchars($lang); ?>">
<head>
    <meta charset="UTF-8">
    <title><?php echo htmlspecialchars($_['heading_home']); ?></title>
</head>
<body>
    <header>
      <h1><?php echo htmlspecialchars($_['heading_home']); ?></h1>
      <nav>
        <ul>
          <li><?php echo htmlspecialchars($_['heading_about']); ?></li>
          <li><?php echo htmlspecialchars($_['button_read_more']); ?></li>
        </ul>
      </nav>
    </header>
</body>
</html>

E pronto—assim nasce um site multi-idioma simples!

Considerações e ideias avançadas

Embora esta solução seja leve, há alguns pontos que vale a pena considerar antes de colocares em produção:

Como detetar o idioma do utilizador? O exemplo usa um parâmetro GET como ?lang=en. Numa aplicação real, também podes usar $_SESSION, $_COOKIE ou analisar o cabeçalho Accept-Language do browser para deteção automática.
Considerações de performance: Para sites pequenos a médios, o impacto de performance do require_once de um ficheiro PHP em cada pedido é praticamente nulo. Se o teu site tiver muito tráfego, considera usar tecnologias de cache de bytecode como APC ou OPcache para otimizar ainda mais.
Escalabilidade: À medida que o número de idiomas ou textos aumenta, gerir os ficheiros manualmente pode tornar-se complicado. Nessa altura, talvez precises de explorar soluções i18n mais profissionais, como a extensão gettext do PHP ou os componentes de localização fornecidos por frameworks.
Consistência nas traduções: Para garantir a consistência dos nomes de marcas e da terminologia em todas as versões de idioma, recomenda-se vivamente usar a funcionalidade de Glossário do O.Translator.
Estratégia de alto nível: Este artigo foca-se na implementação técnica. Se quiseres saber mais sobre a estratégia geral para internacionalização de sites, podes ler o nosso outro artigo mais aprofundado.