Fichiers properties Java
Traduisez les ensembles de ressources Java .properties clé par clé, en conservant les commentaires, les lignes vides et la mise en forme de chaque ligne.
Un fichier .properties associe des clés à des messages, à raison d’une entrée par ligne, selon les règles de lecture de ResourceBundle en Java et de MessageSource dans Spring. Le gestionnaire de fichiers properties traduit la valeur de chaque clé et l’écrit dans une copie du fichier source. Les commentaires, les lignes vides, l’ordre des clés, les séparateurs et les espacements restent inchangés. Seule la valeur d’une clé traduite change.
Configurer la traduction des fichiers properties #
Un fichier properties relève uniquement d’une entrée de fichiers dont le motif se termine par .properties, auquel cas le format est déduit, ou qui définit "format": "properties". Une entrée avec "format": "properties" sélectionne uniquement les fichiers .properties. Un motif général comme src/main/resources/**/* sans ce format ne sélectionne jamais de fichier properties : les fichiers de configuration tels que application.properties ne risquent donc pas d’être traduits par erreur.
Lorsque le nom du fichier contient la langue, comme dans messages_en.properties, chaque fichier cible est créé à côté du fichier source, avec la langue cible au même endroit dans son nom. Les langues sont indiquées dans la notation Java avec des traits de soulignement, pt_BR, que ResourceBundle recherche :
{
"sourceLocale": "en",
"targetLocales": ["de", "pt-BR"],
"files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}Cette configuration crée messages_de.properties et messages_pt_BR.properties. Une langue source régionale est repérée de la même façon : avec "sourceLocale": "en-US", la source est messages_en_US.properties. Définissez localeFormat sur l’entrée pour utiliser une autre forme, par exemple "bcp47" pour pt-BR. Lorsque la source est l’ensemble de ressources par défaut, messages.properties, sans langue dans son nom, indiquez le chemin cible :
{
"pattern": "src/main/resources/messages.properties",
"targetPath": "src/main/resources/messages_[locale].properties"
}La même configuration fonctionne dans la CLI et la GitHub App.
Lecture du fichier #
Les clés et les valeurs sont lues selon les mêmes règles que celles de java.util.Properties :
- Unités. Chaque clé constitue une unité. Une clé qui apparaît deux fois est traduite une seule fois, à partir de la valeur lue par Java, c’est-à-dire la dernière. La traduction est écrite à chaque occurrence.
- Séparateurs.
=,:ou un caractère d’espacement sépare une clé de sa valeur. Des espaces peuvent figurer autour de=et:. - Commentaires et lignes vides. Une ligne dont le premier caractère non blanc est
#ou!est un commentaire. Les commentaires et les lignes vides ne sont jamais envoyés pour traduction. - Continuations. Une ligne se terminant par
\se poursuit sur la ligne suivante, dont les espaces initiaux sont supprimés. Une valeur répartie sur plusieurs lignes est réécrite sur une seule ligne. - Séquences d’échappement.
\uXXXX,\t,\n,\r,\f,\=,\:,\,\\et tout autre caractère échappé sont décodés avant la traduction. Une séquence d’échappement\umal formée fait échouer le traitement du fichier, comme en Java. - Valeurs vides. Une clé dont la valeur est vide ou ne contient que des espaces est conservée telle quelle et n’est pas traduite. Une valeur vide dans un fichier cible est considérée comme non traduite, sauf si la clé figure dans
preservedKeys, qui conserve cette valeur.
Le fichier est lu en UTF-8. Un fichier enregistré en ISO-8859-1 avec des octets bruts représentant des caractères accentués n’est pas pris en charge. Enregistrez-le en UTF-8 ou écrivez ces caractères sous la forme \uXXXX. La marque d’ordre des octets UTF-8 en début de fichier n’est pas conservée.
Écriture des traductions #
Chaque valeur traduite est échappée pour que Java la relise à l’identique : barres obliques inverses, sauts de ligne, tabulations, sauts de page et autres caractères de contrôle, ainsi qu’un espace, = ou : en début de valeur. L’écriture des caractères hors ASCII dépend des valeurs déjà présentes dans le fichier. Les commentaires ne sont pas pris en compte :
| Les valeurs du fichier cible (ou du fichier source, avant la création de la première cible) | Les caractères tels que é ou 中 sont écrits |
|---|---|
| Contiennent déjà du texte UTF-8 brut | Tels quels |
| Contiennent uniquement de l’ASCII | Sous la forme \u00E9, \u4E2D |
Lorsque les valeurs sont échappées, toutes les valeurs écrites le sont, y compris les valeurs verrouillées ou conservées qui contiennent du texte brut dans la source. Un fichier échappé peut être chargé aussi bien par un lecteur UTF-8 que par Properties.load(InputStream), qui lit l’ISO-8859-1.
Les paramètres de substitution tels que {0}, {name} et %s sont conservés dans la traduction. Les règles de citation de MessageFormat en Java, comme l’écriture de '' pour une apostrophe dans un message avec des arguments, ne sont pas appliquées automatiquement.
Conserver les clés et le texte sans les traduire #
lockedKeys, preservedKeys et ignoredKeys portent sur la clé entière, comme dans la version précédente de la CLI : un motif correspond à une clé qui lui est identique, à une clé qui le prolonge après ., / ou -, ou à une clé qui correspond à ce motif interprété comme un motif glob. Ainsi, app correspond à app.title, app.* correspond à app.title et app.menu.save, et *.port correspond à server.port. Un motif commençant par $ est, en revanche, une requête JSONPath sur les clés, comme $["app.title"].
| Option | Résultat dans la cible |
|---|---|
lockedKeys | La valeur source, jamais envoyée pour traduction. |
preservedKeys | La valeur existante dans la cible, ou la valeur source si la cible n’en a pas. |
ignoredKeys | L’entrée entière est exclue, y compris les lignes de continuation. |
lockedPatterns permet de conserver certaines parties d’une valeur sans les traduire. Chaque entrée est une expression régulière utilisant la syntaxe RE2. Chaque correspondance au sein d’une valeur est verrouillée, et ^ et $ s’appliquent aux sauts de ligne à l’intérieur de la valeur :
{
"pattern": "src/main/resources/messages_en.properties",
"lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}Une correspondance est envoyée au modèle sous la forme d’un jeton qu’il doit conserver, puis réécrite octet pour octet. Une traduction qui perd ou modifie une correspondance est rejetée et n’est jamais écrite. Les motifs recherchent des correspondances à l’intérieur de chaque valeur, sans s’étendre sur plusieurs lignes, clés ou commentaires. Dans une valeur contenant une correspondance, les paramètres de substitution tels que {0} et %s sont protégés de la même façon.
RE2 s’exécute en un temps proportionnel à la longueur du texte ; il ne prend donc en charge ni les assertions avant ou arrière ((?=, (?!, (?<=, (?<!), ni les références arrière (\1, \k<name>). Écrivez un caractère hors ASCII sous la forme \x{00E9}, et non \u00E9. La CLI et la GitHub App refusent tout motif qui n’est pas une expression régulière lors de la lecture de la configuration. Si un motif utilise une syntaxe non prise en charge par RE2, l’envoi échoue en indiquant le motif concerné. lockedPatterns ne s’applique qu’aux fichiers properties : une entrée d’un autre format qui le définit est refusée.
--key limite un envoi aux clés qu’il désigne, selon les mêmes règles de correspondance que lockedKeys.
Réutilisation et corrections #
Une clé conserve sa traduction existante tant que sa valeur source n’a pas changé depuis le dernier envoi. Lorsque sa valeur source change, la clé est traduite à nouveau. Les clés présentes uniquement dans un fichier cible en sont supprimées, et les clés cibles suivent l’ordre et la mise en forme de la source.
Un envoi avec --key modifie, en revanche, la cible existante : seules les valeurs sélectionnées changent. Les autres lignes de la cible, y compris les clés présentes uniquement dans celle-ci et ses commentaires, restent inchangées. Une clé sélectionnée absente de la cible est ajoutée à la fin.
Pour corriger une traduction, modifiez-la dans le fichier cible. Pour la régénérer, envoyez-la à nouveau avec --key :
lingo push --key checkout.title --wait