Mentawai Web Framework

Internacionalização (i18n)

O i18n é importante em qualquer aplicação web séria e o Mentawai faz isso automaticamente para você através da classe org.mentawai.i18n.LocaleManager. Claro que não tem problema se você quiser criar o seu site somente em um idioma, mas se você mudar de idéia depois, o Mentawai oferecerá um suporte fácil e automático para a internacionalização.

Você pode fazer o download de uma aplicação simples do Mentawai que usa textos localizados clicando aqui.


Arquivos i18n

O i18n do Mentawai é implementado através de arquivos i18n. Um arquivo i18n (*.i18n) não passa de um arquivo properties com texto localizado. Os arquivos i18n devem ter o seu locale representado no fim do nome do arquivo, por exemplo o conteúdo abaixo poderia ser de um arquivo i18n chamado HelloWorld_en_US.i18n.

###########################
# Example of an i18n file #
###########################

hello = Hello
welcome = Welcome to the online Java community!
					
					

O Mentawai mantém todos os arquivos i18n em memória para rápido acesso e recarregará automaticamente esses arquivos quando houver alguma mudança em disco. Isso é uma característica bastante vantajosa não suportada pelo resource bundle (java.util.ResourceBundle) , que é a solução i18n padrão do Java e que força você a restartar seu servidor web a toda nova mudança no seu texto localizado.

Quando você começar a trabalhar com listas de dados e mensagens dinâmicas,você encontrará arquivos i18n para definir seus textos localizados de uma maneira bem fácil.


Definindo os locales suportados

Se você não fizer nada, o Mentawai vai usar um locale padrão: en_US. Portanto ele espera ao menos encontrar arquivos *_en_US.i18n. Entretanto, você pode definir explicitamente quais locales você escolheu para suportar através do método loadLocales() do ApplicationManager. (Note que se você usar apenas as tags de i18n do Mentawai, você não precisa disso!)

public class ApplicationManager extends org.mentawai.core.ApplicationManager {
	
	public void loadActions() {
		// your actions are defined here...		
	}				
	
	public void loadLocales() {
		// my site will support just one locale
		LocaleManager.add(new Locale("pt", "BR"));
	}
}
				

O código acima indica que o seu site suporta somente o locale pt_BR. Ele ignorará todos os arquivos i18n que não terminarem com _pt_BR.i18n.

Se mais tarde você desejar adicionar o suporte ao francês, você pode especificar um locale extra com o código abaixo:

	public void loadLocales() {
		LocaleManager.add(new Locale("pt", "BR"));
		LocaleManager.add(new Locale("fr"));
	}			
				


Usando as tags i18n nos JSPs

Você pode traduzir sua página JSP utilizando algumas tags simples do Mentawai.

Você indica o texto que quer traduzir na página com a tag <mtw:useI18N />.

O <mtw:useI18N /> procura por arquivos i18n dentro do diretório /i18n na raiz. A tag utiliza o seguinte critério de busca:

[ (1) arquivos especificados na tag, se existirem ]
		↓ 
[ (2) arquivo i18n correspondente ao jsp, se existir ]
		↓
[ (3) arquivo master i18n ]
				
A busca por uma chave retorna no primeiro valor que encontrar seguindo essa ordem (1, 2 e 3). Abaixo esses itens são explicados:
  • (1) - Você pode especificar os arquivos i18n com a tag <mtw:useI18N /> através do atributo files.
    Ex: Se você usar <mtw:useI18N files="somefile, mydir/another" />, então você vai adicionar os arquivos /i18n/somefile e /i18n/mydir/another no caminho de busca.

  • (2) - Se sua página jsp for /mypage.jsp, o Mentawai automaticamente procura por um arquivo chamado /i18n/mypage_loc.i18n. Note que a estrutura dos diretórios é respeitada, ou seja, se o seu arquivo estiver em /pags/mypage.jsp, o Mentawai vai procurar por um arquivo chamado /i18n/pags/mypage_loc.i18n

  • (3) - O último arquivo i18n no caminho da busca é, por padrão, /i18n/master_loc.i18n.
  • Note que esses arquivos não precisam existir. Se isso acontecer a chave é procurada pelos arquivos conforme forem encontrados.

    Esse caminho de busca é útil porque permite que você sobrescreva suas chaves se necessário.

    Se desejar você pode mudar o nome do arquivo i18n master com o código abaixo:

    	public void loadLocales() {
    		LocaleManager.add(new Locale("pt", "BR"));
    		LocaleManager.add(new Locale("fr"));
    		LocaleManager.setMaster("mywebsite"); // master = /mywebsite_loc.i18n
    	}			
    				

    Uma vez declarado na página JSP que você quer usar arquivos i18n através da tag <mtw:useI18N />, você pode exibir o texto traduzido através da tag do Mentawai: <mtw:i18n key="hello" /> .

    Se você precisar de imagens localizadas, você pode usar a tag <mtw:i18nDir /> para exibir o locale utilizado, por exemplo pt_BR. Portanto você teria sua imagem exibida dessa maneira:

    <img src="/images/<mtw:i18nDir />/hello.gif">


    Como o locale do usuário é determinado

    Por padrão, o locale do usuário é o locale do browser, em outras palavras, é o locale que o browser envia junto com cada requisição HTTP.

    Você também pode forçar que o locale do usuário seja um específico, que pode vir do banco de dados ou de um cookie, por exemplo. Para tal, tudo o que você precisa fazer é colocar o locale do usuário na sessão com o código abaixo:

    	session.setAttribute(BaseLoginAction.LOCALE_KEY, userLocaleFromDatabase);
    		

    Se você estiver usando a action org.mentawai.action.BaseLoginAction para a autenticação do usuário, você pode também usar o método setUserLocale() para conseguir o mesmo efeito.

    O que acontece se o locale do usuário (que veio do banco de dados, do browser, ou de um cookie) não for suportado pelo site?

    O Mentawai usa a seguinte regra para retornar o locale:

    • Digamos que o locale enviado pelo browser seja en_UK.
    • O Mentawai primeiro verifica se o locale é suportado, em outras palavras, ele procura por en_UK.
    • Se o en_UK não for encontrado, ele procura pelo locale en, de inglês geral.
    • Se o en não for encontrado, ele procura pelo primeiro locale que tiver a mesma língua, como por exemplo en_US, en_AU, etc.
    • Se não existir locale da mesma língua, então retornará o locale padrão, em outras palavras, o primeiro locale adicionado no LocaleManager.