Internacionalização com CakePHP

Internacionalização com CakePHP: O mercado de tecnologia não possui fronteiras. Hoje, você pode estar desenvolvendo um sistema em São José do Rio Preto, mas amanhã seu principal cliente pode ser uma empresa em Portugal, nos Estados Unidos ou no Japão. Se o seu código está repleto de frases fixas em português (“hardcoded”), você terá um problema gigantesco para escalar.

Como especialista em CakePHP, preparei este vigésimo segundo artigo da nossa série para ensinar você a dominar a Internacionalização (i18n). Vamos transformar sua aplicação em um sistema global, capaz de falar qualquer língua com apenas algumas configurações, mantendo a elegância e a organização que o framework exige.

Internacionalização (i18n): Preparando seu app para vários idiomas no CakePHP

Internacionalização com CakePHP: A Internacionalização, frequentemente abreviada como i18n (o número 18 representa as letras entre o ‘i’ e o ‘n’), é o processo de projetar e preparar sua aplicação para suportar diversos idiomas e formatos regionais (como moedas e datas) sem a necessidade de alterações estruturais no código-fonte.

No CakePHP, a i18n é tratada como um cidadão de primeira classe. O framework utiliza o padrão da indústria chamado gettext, que separa as mensagens de tradução do código lógico, facilitando a vida tanto dos desenvolvedores quanto dos tradutores.

1. O básico: A função de tradução __()

A regra de ouro para um app internacionalizável é: nunca escreva texto puro na sua View ou no seu Controller. Em vez de escrever echo "Bem-vindo";, você deve usar a função global de tradução do CakePHP.

Como funciona:

PHP

// Na sua View ou Controller
echo __('Bem-vindo');

A função __() faz duas coisas:

1. Verifica qual é o idioma atual do sistema.
2. Procura em um arquivo de tradução se existe um correspondente para a chave “Bem-vindo”. Se não encontrar, ela exibe o texto original.

Existem variações poderosas dessa função, como a __n(), usada para lidar com plurais:

PHP

echo __n('{0} artigo encontrado', '{0} artigos encontrados', $total, $total);

2. Estrutura de Pastas e Arquivos .po

O CakePHP organiza as traduções na pasta resources/locales/. Cada idioma possui sua própria subpasta (usando o código ISO, como pt_BR, en_US, es_ES). Dentro delas, vivem os arquivos .po (Portable Object).

Exemplo de caminho:

• resources/locales/pt_BR/default.po (Português Brasil)
• resources/locales/en_US/default.po (Inglês EUA)

Anatomia de um arquivo .po:

Snippet de código

msgid "Bem-vindo"
msgstr "Welcome"

msgid "{0} artigo encontrado"
msgid_plural "{0} artigos encontrados"
msgstr[0] "{0} article found"
msgstr[1] "{0} articles found"

3. Extraindo as traduções automaticamente (I18n Shell)

Você não precisa criar esses arquivos .po manualmente para cada palavra do seu sistema. O CakePHP possui uma ferramenta CLI (Command Line Interface) fantástica que varre seu projeto em busca das funções __() e gera os arquivos para você.

No seu terminal, execute:

Bash

bin/cake i18n extract

O assistente perguntará onde você deseja salvar e quais pastas quer escanear. Ao final, ele gerará um arquivo default.pot (template). Basta renomeá-lo para default.po dentro da pasta do idioma desejado e começar a traduzir.

4. Mudando o idioma dinamicamente

Como o CakePHP sabe qual idioma exibir? Isso é controlado pela classe I18n. Você pode definir o idioma globalmente no seu AppController.php ou criar um Middleware (Artigo 17) que detecta a preferência do usuário.

Detectando o idioma pela URL ou Sessão:

PHP

use Cake\I18n\I18n;

public function beforeFilter(\Cake\Event\EventInterface $event)
{
    parent::beforeFilter($event);
    
    // Supondo que você salve o idioma na sessão ou venha pela URL
    $lang = $this->request->getParam('lang', 'pt_BR');
    I18n::setLocale($lang);
}

Dica para SEO: URLs como meusite.com/en/artigos são muito melhores para o Google do que usar apenas sessões. Use o roteamento avançado (Artigo 12) para gerenciar o prefixo do idioma.

5. Localização (L10n): Datas, Números e Moedas

Internacionalizar não é apenas traduzir palavras. É garantir que o usuário em Londres veja a data como DD/MM/YYYY e o usuário em Nova York veja como MM/DD/YYYY.

O CakePHP utiliza a biblioteca ICU integrada para formatar esses dados automaticamente baseando-se no locale definido.

PHP

use Cake\I18n\Number;
use Cake\I18n\FrozenTime;

// Formatação de Moeda
echo Number::currency(1500.50); // R$ 1.500,50 (em pt_BR) ou $1,500.50 (em en_US)

// Formatação de Data
$data = FrozenTime::now();
echo $data->i18nFormat(\IntlDateFormatter::LONG); 
// "13 de abril de 2026" (pt_BR) ou "April 13, 2026" (en_US)

6. Traduzindo conteúdo do Banco de Dados (Translate Behavior)

E quanto às centenas de artigos em um blog? Eles não estão nos arquivos .po, eles estão no MySQL. Para traduzir campos de tabelas, o CakePHP oferece o Translate Behavior.

Ele permite que você mantenha uma tabela centralizada de traduções (i18n) e o framework faz o join automaticamente para buscar o título e o corpo do artigo no idioma selecionado.

Configurando o Behavior na Table:

PHP

// src/Model/Table/ArtigosTable.php
public function initialize(array $config): void
{
    $this->addBehavior('Translate', ['fields' => ['titulo', 'corpo']]);
}

Ao salvar um artigo, você pode salvar várias traduções ao mesmo tempo, e ao ler, o CakePHP traz a versão correta de forma transparente.

7. Boas Práticas para um App Global

Para ser um desenvolvedor sênior em CakePHP, siga estas diretrizes:

1. Use chaves descritivas ou o texto original: Há quem prefira usar chaves ('home.welcome_message') e quem prefira o texto original ('Bem-vindo ao nosso portal'). O CakePHP funciona bem com ambos, mas o texto original facilita a leitura do código.
2. Não concatene frases de tradução:
   • Errado: __('O erro foi') . $erro . __('tente novamente')
   • Certo: __('O erro foi {0}, tente novamente', $erro)
   • Isso é vital porque a ordem das palavras muda drasticamente entre idiomas (como Alemão e Japonês).
3. Localize seus formulários: Use o FormHelper em conjunto com as traduções para os labels de cada input.
4. Imagens com texto: Evite! Se precisar, use CSS para sobrepor o texto traduzido a uma imagem de fundo, ou use o idioma como parte do nome do arquivo (ex: bandeira-en.png).

Conclusão: O Mundo é o seu Limite

Preparar sua aplicação para vários idiomas com i18n no CakePHP não é apenas uma tarefa técnica; é uma decisão estratégica de negócio. Ao modularizar suas strings e utilizar as ferramentas de localização do framework, você remove as barreiras geográficas do seu software.

Seja para um blog, para um portal de empregos ou para um novo SaaS internacional, o CakePHP garante que a transição entre idiomas seja suave para o usuário e organizada para você, desenvolvedor. Sua aplicação agora está pronta para ser cidadã do mundo.

Com este domínio sobre a internacionalização, você eleva a qualidade do seu portfólio a um nível global.

Mas antes de dominar o CakePHP, se for o seu caso, toda jornada tem um início. Vamos entender quais são os conhecimentos básicos necessários para aproveitar ao máximo este poderoso framework. Para iniciar seus estudos no CakePHP, você precisará dominar as seguintes tecnologias:

E se você gosta do nosso conteúdo, não deixe de contribuir adquirindo os serviços e produtos dos nossos apoiadores e empresas que somos associados.

Dica de Especialista: Se o seu projeto for muito grande, utilize ferramentas como o Poedit ou serviços na nuvem para gerenciar seus arquivos .po. Eles permitem que tradutores profissionais trabalhem nos arquivos sem nunca precisarem tocar no seu código-fonte!