enum abstract Lang(String)

Lang oferece um sistema de internacionalização que permite carregar e acessar textos traduzidos através de enums gerados dinamicamente a partir de arquivos de recursos.

A abordagem recomendada é usar arquivos JSON embarcados como recursos e acessar as chaves através dos valores de enum gerados automaticamente pela macro.

É recomendado usar esta classe tanto por importação direta quanto como extensão estática:

// Importação normal
import util.kit.lang.Lang;

// Extensão estática
using util.kit.lang.Lang;

Exemplos de uso com recursos embarcados:

1. Configuração dos recursos no arquivo de compilação (ex: build.hxml):

--resource res/lang-pt.json@lang-pt
--resource res/lang-en.json@lang-en

1. Carregando um idioma e acessando valores através de enum:

// Carrega o dicionário em português
Lang.setLanguage("PT");

// Acessando valores através de enums gerados automaticamente
var saudacao = Lang.GREETING; // "Olá mundo!"

// Alternando para inglês
Lang.setLanguage("EN");
var greeting = Lang.GREETING; // "Hello world!"

1. Usando placeholders para substituição dinâmica:

// Usando o método params()
var msg = Lang.WELCOME.params("João", "5");  // "Bem-vindo, João! Você tem 5 mensagens."

// Outra forma seria:
var msg = "WELCOME".lang("João", "5");  // Usando extensão estática

1. Acessando valores aninhados:

// Os valores aninhados são automaticamente transformados em enums com underscores
var erro = Lang.MESSAGES_ERRORS_NOT_FOUND;  // "Registro não encontrado"

// Acessando valores de array (também gera enum)
var domingo = Lang.DAYS_0;  // "Domingo"
var sexta = Lang.DAYS_5;    // "Sexta"

Estrutura do arquivo de recursos JSON:

{
    "GREETING": "Olá mundo!",
    "WELCOME": "Bem-vindo, $v! Você tem $v mensagens.",
    "MESSAGES": {
        "SUCCESS": "Operação realizada com sucesso",
        "ERRORS": {
            "NOT_FOUND": "Registro não encontrado",
            "FORBIDDEN": "Acesso negado"
        }
    },
    "DAYS": ["Domingo", "Segunda", "Terça", "Quarta", "Quinta", "Sexta", "Sábado"]
}

Note que todas as chaves são tratadas como case-insensitive. Portanto, "welcome", "Welcome" e "WELCOME" são consideradas a mesma chave.

Responsabilidades:

• Geração automática de enums: Cria enums a partir da estrutura dos arquivos JSON de idioma
• Carregamento de recursos embarcados: Carrega dicionários a partir de recursos JSON
• Gerenciamento de dicionário de strings: Armazena e organiza textos associados a chaves específicas
• Substituição de placeholders: Substitui marcadores de texto ($v) por valores dinâmicos
• Suporte a estruturas aninhadas: Permite organizar o dicionário em estruturas hierárquicas e arrays
• Normalização de chaves: Converte todas as chaves para maiúsculas para tornar o sistema case-insensitive

Forma alternativa (legado):

Também é possível carregar dicionários diretamente através de objetos:

// Carregando dicionário manualmente
var dictionary = {
    GREETING: "Olá mundo!",
    FAREWELL: "Adeus!"
};
Lang.load(dictionary);

// Acessando valores
var texto = Lang.lang("GREETING"); // "Olá mundo!"

Como lidar com o cache do VSCode:

Quando você modifica arquivos de recursos JSON externos, o VSCode não atualiza automaticamente as opções de autocompletar/intellisense devido ao cache do completion server. Isso significa que novas chaves adicionadas aos arquivos JSON não aparecerão no autocompletar até que você reinicie o servidor de compilação.

Para resolver este problema, você deve registrar uma dependência explícita entre seu código e os arquivos JSON no seu arquivo HXML:

# Registra dependência dos arquivos de idioma para atualizar o cache do completion server
--macro util.kit.lang.LangMacro.depends("res/lang-pt.json")
--macro util.kit.lang.LangMacro.depends("res/lang-en.json")

# Registra recursos normalmente
--resource res/lang-pt.json@lang-pt
--resource res/lang-en.json@lang-en

Com essa configuração, sempre que você modificar um dos arquivos JSON listados, o VSCode reconhecerá a necessidade de recompilar e atualizar o cache do completion server, garantindo que as novas chaves apareçam corretamente no autocompletar.

{
    "GREETING": "Olá mundo!",
    "WELCOME": "Bem-vindo, $v!",
    "MESSAGES": {
        "SUCCESS": "Operação realizada com sucesso",
        "ERROR": "Ocorreu um erro"
    }
}

--resource res/lang-pt.json@lang-pt
--resource res/lang-en.json@lang-en

// Carrega o idioma
Lang.setLanguage("PT");

// Acessa textos via enum
trace(Lang.GREETING);                   // "Olá mundo!"
trace(Lang.WELCOME.params("João"));     // "Bem-vindo, João!"
trace(Lang.MESSAGES_SUCCESS);           // "Operação realizada com sucesso"

// Com o texto "Olá, $v! Você tem $v mensagens."
var msg = Lang.WELCOME.params("João", "5");
// Resultado: "Olá, João! Você tem 5 mensagens."