Internacionalização PHP: como falar com o mundo em um só idioma

Por que seu site PHP precisa falar diferentes idiomas?

Imagine: você criou o produto perfeito — rápido, prático, que resolve problemas. Mas há um problema: sua interface fala apenas português. Potenciais clientes da Alemanha, Japão ou Brasil simplesmente fecham a aba, sem entender nenhum botão. Isso não é apenas lucro perdido — é a perda de mercados inteiros.

Internacionalização (i18n — de "internationalization", onde 18 letras entre i e n) e localização (l10n) não são um "checklist" para startups, mas uma ferramenta estratégica. Muitos desenvolvedores temem essa palavra, achando que terão que reescrever todo o código. Na verdade, uma organização inteligente de traduções em PHP é um processo elegante que torna o código mais limpo e o negócio mais global.

Neste artigo, vamos explorar três abordagens reais para internacionalização de aplicações PHP: desde arrays simples até a poderosa extensão intl e o clássico gettext. Você aprenderá não apenas a traduzir texto, mas a trabalhar corretamente com datas, números e formas plurais — já que em árabe, polonês ou português existem regras de flexão específicas.

Principais abordagens para i18n em PHP

Antes de escrever código, é preciso escolher a arquitetura. Basicamente, os métodos se dividem em três categorias. Qual escolher depende do tamanho do projeto e dos requisitos de desempenho.

1. Arrays e arquivos ini (abordagem DIY)

A maneira mais simples é armazenar traduções em arrays associativos ou arquivos .ini. Ideal para projetos pequenos ou MVPs.

// lang/pt_BR.php\nreturn [\n    'welcome' => 'Bem-vindo ao site!',\n    'logout' => 'Sair',\n    'cart_empty' => 'Carrinho vazio'\n];\n\n// lang/en.php\nreturn [\n    'welcome' => 'Welcome to the website!',\n    'logout' => 'Logout',\n    'cart_empty' => 'Cart is empty'\n];

Usar é simples: inclua o arquivo correto com base na sessão ou cookie do usuário.

function __($key) {\n    static $lang = null;\n    if ($lang === null) {\n        $locale = $_SESSION['lang'] ?? 'pt_BR';\n        $lang = include "lang/{$locale}.php";\n    }\n    return $lang[$key] ?? $key;\n}\n\necho __('welcome'); // Bem-vindo ao site!

Vantagens: simplicidade, não requer extensões, fácil de cachear (pode até salvar no Redis).
\nDesvantagens: sem suporte a formas plurais (você terá que criar sua própria solução), inconveniente para projetos grandes (muitas chaves em um único arquivo).

2. Gettext — o clássico do gênero

Gettext é o padrão de facto para internacionalização no mundo Unix. No PHP, está disponível através da extensão gettext. É uma ferramenta poderosa usada no WordPress, Drupal e Symfony.

Primeiro, crie arquivos .po (por exemplo, para português do Brasil):

# pt_BR/LC_MESSAGES/messages.po\nmsgid "Hello, %s!"\nmsgstr "Olá, %s!"\n\nmsgid "You have %d new message"\nmsgid_plural "You have %d new messages"\nmsgstr[0] "Você tem %d nova mensagem"\nmsgstr[1] "Você tem %d novas mensagens"

Depois, compile para um arquivo .mo (usando a ferramenta msgfmt). No código PHP, fica assim:

putenv('LC_ALL=pt_BR.UTF-8');\nsetlocale(LC_ALL, 'pt_BR.UTF-8');\nbindtextdomain('messages', './locale');\ntextdomain('messages');\n\necho gettext('Hello, %s!', 'João'); // Olá, João!\n\n// Formas plurais — mágica:\necho ngettext('%d message', '%d messages', 3); // 3 mensagens

A propósito, para acelerar o desenvolvimento, use o Poedit — ele destaca strings não traduzidas.

3. Extensão Intl (PHP 5.3+)

Se você precisa não apenas traduzir texto, mas formatar corretamente números, datas ou moedas de acordo com os padrões do país — use Intl. É uma camada sobre a biblioteca ICU (International Components for Unicode).

// Formatação de números