Propriedades Java

Traduza pacotes de recursos Java .properties, uma chave por vez, preservando os comentários, as linhas em branco e a formatação de cada linha.

Um arquivo .properties associa chaves a mensagens, com uma entrada por linha, conforme a leitura feita por ResourceBundle do Java e MessageSource do Spring. O processador de arquivos properties traduz o valor de cada chave e o grava em uma cópia do arquivo de origem. Os comentários, as linhas em branco, a ordem das chaves, os separadores e o espaçamento são preservados. Só o valor de uma chave traduzida muda.

Configure a tradução de propriedades #

Um arquivo de propriedades só é associado a uma entrada de arquivos cujo padrão termina em .properties, caso em que o formato é inferido, ou que define "format": "properties". Uma entrada com "format": "properties" seleciona apenas arquivos .properties. Um padrão amplo, como src/main/resources/**/*, sem esse formato nunca seleciona arquivos de propriedades. Assim, arquivos de configuração como application.properties não são traduzidos por engano.

Quando o nome do arquivo contém o idioma, como em messages_en.properties, cada arquivo de destino é criado ao lado dele, com o idioma de destino na mesma posição do nome. Os idiomas são escritos no formato do Java com sublinhado, pt_BR, usado por ResourceBundle na busca:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "pt-BR"],
  "files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}

Isso grava messages_de.properties e messages_pt_BR.properties. Um idioma de origem regional é localizado da mesma forma: com "sourceLocale": "en-US", a origem é messages_en_US.properties. Defina localeFormat na entrada para usar outro formato, como "bcp47" para pt-BR. Quando a origem é o pacote padrão, messages.properties, sem idioma no nome, declare o caminho de destino:

json
{
  "pattern": "src/main/resources/messages.properties",
  "targetPath": "src/main/resources/messages_[locale].properties"
}

A mesma configuração funciona na CLI e no GitHub App.

Como o arquivo é lido #

As chaves e os valores são lidos da mesma forma que em java.util.Properties:

  • Unidades. Cada chave é uma unidade. Uma chave que aparece duas vezes é traduzida uma única vez, usando o último valor, que é o que o Java lê. A tradução é gravada em todas as ocorrências.
  • Separadores. =, : ou um caractere de espaço em branco separa a chave de seu valor, com espaços opcionais ao redor de = e :.
  • Comentários e linhas em branco. Uma linha é um comentário quando seu primeiro caractere que não seja um espaço em branco é # ou !. Comentários e linhas em branco nunca são enviados para tradução.
  • Continuações. Uma linha que termina em \ continua na linha seguinte, cujos espaços iniciais são removidos. Um valor com continuação é gravado de volta em uma única linha.
  • Sequências de escape. \uXXXX, \t, \n, \r, \f, \=, \:, \ , \\ e qualquer outro caractere com escape são decodificados antes da tradução. Uma sequência de escape \u malformada causa uma falha no processamento do arquivo, assim como no Java.
  • Valores vazios. Uma chave com valor vazio ou composto apenas por espaços é mantida como está, sem tradução. Um valor vazio no destino é considerado não traduzido, exceto quando a chave está em preservedKeys, que preserva esse valor.

O arquivo é lido como UTF-8. Arquivos salvos em ISO-8859-1 com bytes de caracteres acentuados sem escape não são compatíveis; salve-os como UTF-8 ou escreva esses caracteres como \uXXXX. A marca de ordem de bytes UTF-8 no início do arquivo não é preservada.

Como as traduções são gravadas #

Cada valor traduzido recebe sequências de escape para que o Java o leia novamente sem alterações. Isso se aplica a barras invertidas, quebras de linha, tabulações, avanços de página e outros caracteres de controle, além de um espaço, = ou : no início do valor. Caracteres fora do ASCII são gravados de acordo com os valores já presentes no arquivo. Os comentários não contam:

Os valores do arquivo de destino (ou da origem, antes de existir o primeiro destino)Caracteres como é ou 中 são gravados
Já contêm texto UTF-8 sem escapeComo estão
Contêm apenas ASCIIComo \u00E9, \u4E2D

Quando são usadas sequências de escape, elas são aplicadas a todos os valores gravados, inclusive a valores bloqueados ou preservados que contenham texto sem escape na origem. Um arquivo com sequências de escape pode ser carregado tanto por um leitor UTF-8 quanto por Properties.load(InputStream), que lê ISO-8859-1.

Marcadores como {0}, {name} e %s são mantidos na tradução. As regras de uso de aspas de MessageFormat do Java, como escrever '' para representar um apóstrofo em uma mensagem com argumentos, não são aplicadas automaticamente.

Mantenha chaves e texto sem tradução #

lockedKeys, preservedKeys e ignoredKeys buscam correspondências na chave inteira, como na versão anterior da CLI: um padrão corresponde a uma chave idêntica a ele, a uma chave que continua o padrão após ., / ou -, ou a uma chave que corresponde a ele como padrão glob. Assim, app corresponde a app.title, app.* corresponde a app.title e app.menu.save, e *.port corresponde a server.port. Já um padrão que começa com $ é uma consulta JSONPath sobre as chaves, como $["app.title"].

OpçãoResultado no destino
lockedKeysO valor de origem, que nunca é enviado para tradução.
preservedKeysO valor existente no destino ou, se não houver, o valor de origem.
ignoredKeysA entrada inteira é omitida, incluindo as linhas de continuação.

lockedPatterns mantém partes de um valor sem tradução. Cada entrada é uma expressão regular na sintaxe RE2, e cada correspondência encontrada em um valor é bloqueada. ^ e $ reconhecem as quebras de linha dentro de um valor:

json
{
  "pattern": "src/main/resources/messages_en.properties",
  "lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}

Cada correspondência é enviada ao modelo como um token que ele deve preservar e é gravada de volta byte por byte. Uma tradução que omite ou altera uma correspondência é rejeitada e nunca é gravada. Os padrões buscam correspondências dentro de cada valor, sem abranger diferentes linhas, chaves ou comentários. Em um valor com uma correspondência, marcadores como {0} e %s são protegidos da mesma forma.

O RE2 é executado em tempo proporcional ao tamanho do texto, por isso não oferece asserções de contexto ((?=, (?!, (?<=, (?<!) nem referências retroativas (\1, \k<name>). Escreva um caractere fora do ASCII como \x{00E9}, não como \u00E9. Ao ler a configuração, a CLI e o GitHub App rejeitam padrões que não sejam expressões regulares. Se um padrão usar uma sintaxe não compatível com RE2, o envio falha e informa qual é o padrão. lockedPatterns se aplica apenas a arquivos de propriedades: uma entrada de outro formato que o defina é rejeitada.

--key restringe um envio às chaves especificadas, usando as mesmas regras de correspondência de lockedKeys.

Reutilização e correções #

Uma chave mantém a tradução existente enquanto seu valor de origem não mudar desde o último envio. Quando o valor de origem muda, a chave é traduzida novamente. As chaves que existem apenas no arquivo de destino são removidas dele, e as chaves de destino seguem a ordem e a formatação da origem.

Já um envio com --key edita o destino existente: só os valores selecionados mudam. As demais linhas do destino, incluindo suas chaves exclusivas e seus comentários, permanecem como estão. Uma chave selecionada que não existe no destino é adicionada ao final dele.

Para corrigir uma tradução, edite-a no arquivo de destino. Para gerá-la novamente, faça outro envio com --key:

sh
lingo push --key checkout.title --wait