Ficheiros properties de Java
Traduza conjuntos de recursos .properties de Java, uma chave de cada vez, preservando os comentários, as linhas em branco e a disposição de cada linha.
Um ficheiro .properties associa chaves a mensagens, com uma entrada por linha, tal como são lidas por ResourceBundle de Java e MessageSource de Spring. O processador de ficheiros properties traduz o valor de cada chave e escreve-o numa cópia do ficheiro de origem. Os comentários, as linhas em branco, a ordem das chaves, os separadores e os espaços mantêm-se inalterados. Só o valor de uma chave traduzida é alterado.
Configurar a tradução de ficheiros properties #
Um ficheiro properties só é abrangido por uma entrada de ficheiros cujo padrão termine em .properties, caso em que o formato é inferido, ou que defina "format": "properties". Uma entrada com "format": "properties" seleciona apenas ficheiros .properties. Um padrão abrangente como src/main/resources/**/*, sem esse formato definido, nunca seleciona um ficheiro properties. Assim, ficheiros de configuração como application.properties não são traduzidos por engano.
Quando o nome do ficheiro contém o idioma, como em messages_en.properties, cada ficheiro de destino é criado junto do original, com o idioma de destino na mesma posição do nome. Os idiomas são escritos no formato de Java com sublinhado, pt_BR, que ResourceBundle procura:
{
"sourceLocale": "en",
"targetLocales": ["de", "pt-BR"],
"files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}Esta configuração cria messages_de.properties e messages_pt_BR.properties. Uma variante regional do idioma de origem é identificada da mesma forma: com "sourceLocale": "en-US", o ficheiro de origem é messages_en_US.properties. Defina localeFormat na entrada para usar outro formato, como "bcp47" para pt-BR. Quando a origem é o conjunto de recursos predefinido, messages.properties, sem idioma no nome, declare o caminho de destino:
{
"pattern": "src/main/resources/messages.properties",
"targetPath": "src/main/resources/messages_[locale].properties"
}A mesma configuração funciona na CLI e na GitHub App.
Como o ficheiro é lido #
As chaves e os valores são lidos da mesma forma que java.util.Properties os lê:
- Unidades. Cada chave é uma unidade. Uma chave que aparece duas vezes é traduzida uma única vez, usando o valor que Java lê, ou seja, o último. A tradução é escrita em todas as ocorrências.
- Separadores. A chave e o respetivo valor são separados por
=,:ou espaços em branco, com espaços opcionais em redor de=e:. - Comentários e linhas em branco. Uma linha cujo primeiro caráter que não seja um espaço em branco é
#ou!é um comentário. Os comentários e as 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 é escrito de novo numa única linha. - Sequências de escape.
\uXXXX,\t,\n,\r,\f,\=,\:,\,\\e qualquer outro caráter com escape são descodificados antes da tradução. Uma sequência de escape\umalformada faz falhar o processamento do ficheiro, tal como em Java. - Valores vazios. Uma chave cujo valor está vazio ou contém apenas espaços é mantida tal como está e não é traduzida. Um valor vazio num ficheiro de destino é considerado não traduzido, exceto se a chave estiver em
preservedKeys, caso em que o valor vazio é mantido.
O ficheiro é lido como UTF-8. Não são suportados ficheiros guardados em ISO-8859-1 com bytes de carateres acentuados sem escape; guarde-os como UTF-8 ou escreva esses carateres como \uXXXX. Se existir uma marca de ordem de bytes UTF-8 no início do ficheiro, esta não é mantida.
Como as traduções são escritas #
Cada valor traduzido é escrito com as sequências de escape necessárias para que Java o volte a ler sem alterações. Isto aplica-se a barras invertidas, quebras de linha, tabulações, avanços de página e outros carateres de controlo, bem como a um espaço, = ou : no início do valor. Os carateres fora do conjunto ASCII são escritos de acordo com os valores já existentes no ficheiro. Os comentários não contam:
| Os valores do ficheiro de destino (ou do ficheiro de origem, antes de existir o primeiro destino) | Os carateres como é ou 中 são escritos |
|---|---|
| Já contêm texto UTF-8 sem escape | Tal como estão |
| Contêm apenas ASCII | Como \u00E9, \u4E2D |
Quando se usam sequências de escape, estas são aplicadas a todos os valores escritos, incluindo valores bloqueados ou preservados que contenham texto sem escape na origem. Um ficheiro com sequências de escape pode ser carregado tanto por um leitor UTF-8 como por Properties.load(InputStream), que lê ISO-8859-1.
Os marcadores de posição, como {0}, {name} e %s, são mantidos na tradução. As regras de utilização de aspas de MessageFormat de Java, como escrever '' para representar um apóstrofo numa mensagem com argumentos, não são aplicadas automaticamente.
Manter chaves e texto sem tradução #
lockedKeys, preservedKeys e ignoredKeys fazem a correspondência com a chave completa, tal como na versão anterior da CLI: um padrão corresponde a uma chave igual a si, a uma chave que o prolonga após ., / ou -, ou a uma chave que corresponda ao padrão interpretado como 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 comece por $ é uma consulta JSONPath sobre as chaves, como $["app.title"].
| Opção | Resultado no destino |
|---|---|
lockedKeys | O valor de origem, que nunca é enviado para tradução. |
preservedKeys | O valor existente no destino ou o valor de origem, se não existir nenhum no destino. |
ignoredKeys | A entrada é omitida na totalidade, incluindo as linhas de continuação. |
lockedPatterns mantém partes de um valor sem tradução. Cada entrada é uma expressão regular em sintaxe RE2, e todas as correspondências encontradas em cada valor são bloqueadas. ^ e $ correspondem às posições de quebra de linha dentro de um valor:
{
"pattern": "src/main/resources/messages_en.properties",
"lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}Cada correspondência é enviada ao modelo como um marcador que este tem de manter e é escrita de novo sem alterar um único byte. Uma tradução que perca ou altere uma correspondência é rejeitada e nunca é escrita. Os padrões procuram correspondências dentro de cada valor, não entre linhas, chaves ou comentários. Num valor com uma correspondência, os marcadores de posição como {0} e %s são protegidos da mesma forma.
O tempo de execução de RE2 é proporcional ao texto, pelo que não suporta asserções de contexto ((?=, (?!, (?<=, (?<!) nem referências anteriores (\1, \k<name>). Escreva um caráter fora do conjunto ASCII como \x{00E9}, não como \u00E9. Ao lerem a configuração, a CLI e a GitHub App rejeitam qualquer padrão que não seja uma expressão regular. Se um padrão usar sintaxe não suportada por RE2, o envio falha e o padrão é identificado. lockedPatterns aplica-se apenas a ficheiros properties: uma entrada de outro formato que o defina é rejeitada.
--key limita um envio às chaves que indica, usando as mesmas regras de correspondência de lockedKeys.
Reutilização e correções #
Uma chave mantém a tradução existente enquanto o respetivo valor de origem não mudar desde o último envio. Quando um valor de origem muda, essa chave é traduzida novamente. As chaves que só existem num ficheiro de destino são removidas desse ficheiro, e as chaves de destino seguem a ordem e a disposição da origem.
Já um envio com --key edita o ficheiro de destino existente: só os valores selecionados são alterados. As restantes linhas do destino, incluindo as chaves que só existem nesse ficheiro e os seus comentários, mantêm-se inalteradas. Uma chave selecionada que não exista no destino é acrescentada no fim.
Para corrigir uma tradução, edite-a no ficheiro de destino. Para a gerar novamente, volte a enviá-la com --key:
lingo push --key checkout.title --wait