Java-Properties
Übersetze Java-Ressourcenbündel im .properties-Format Schlüssel für Schlüssel – Kommentare, Leerzeilen und das Layout jeder Zeile bleiben erhalten.
Eine .properties-Datei ordnet Schlüsseln Nachrichten zu, mit einem Eintrag pro Zeile – so, wie Javas ResourceBundle und Springs MessageSource sie lesen. Der Dateihandler für properties übersetzt den Wert jedes Schlüssels und schreibt ihn in eine Kopie der Quelldatei. Kommentare, Leerzeilen, die Reihenfolge der Schlüssel, Trennzeichen und Abstände bleiben unverändert. Nur der Wert eines übersetzten Schlüssels ändert sich.
Properties-Übersetzung konfigurieren #
Eine Properties-Datei wird nur von einem Dateieintrag erfasst, dessen Muster auf .properties endet, sodass das Format daraus abgeleitet wird, oder der "format": "properties" festlegt. Ein Eintrag mit "format": "properties" wählt nur .properties-Dateien aus. Ein weit gefasstes Muster wie src/main/resources/**/* ohne diese Formatangabe wählt niemals eine Properties-Datei aus. So werden Konfigurationsdateien wie application.properties nicht versehentlich übersetzt.
Wenn der Dateiname die Sprache enthält, wie in messages_en.properties, wird jede Zieldatei daneben abgelegt, mit der Zielsprache an derselben Stelle im Namen. Sprachen werden in Javas Schreibweise mit Unterstrichen angegeben, pt_BR, nach der ResourceBundle sucht:
{
"sourceLocale": "en",
"targetLocales": ["de", "pt-BR"],
"files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}Dabei werden messages_de.properties und messages_pt_BR.properties geschrieben. Eine regionale Quellsprache wird auf dieselbe Weise gefunden: Bei "sourceLocale": "en-US" ist die Quelle messages_en_US.properties. Setze im Eintrag localeFormat, um eine andere Schreibweise zu verwenden, etwa "bcp47" für pt-BR. Wenn die Quelle das Standardbündel messages.properties ohne Sprache im Namen ist, gib den Zielpfad an:
{
"pattern": "src/main/resources/messages.properties",
"targetPath": "src/main/resources/messages_[locale].properties"
}Dieselbe Konfiguration funktioniert in der CLI und in der GitHub App.
So wird die Datei gelesen #
Schlüssel und Werte werden genauso gelesen wie von java.util.Properties:
- Einheiten. Jeder Schlüssel bildet eine Einheit. Ein Schlüssel, der zweimal vorkommt, wird einmal übersetzt, und zwar mit dem Wert, den Java liest – also dem letzten. Jedes Vorkommen erhält diese Übersetzung.
- Trennzeichen.
=,:oder Leerraum trennen einen Schlüssel von seinem Wert. Vor und nach=und:sind optionale Leerzeichen erlaubt. - Kommentare und Leerzeilen. Eine Zeile, deren erstes Zeichen nach etwaigem Leerraum
#oder!ist, gilt als Kommentar. Kommentare und Leerzeilen werden niemals zur Übersetzung gesendet. - Zeilenfortsetzungen. Eine Zeile, die mit
\endet, wird in der nächsten Zeile fortgesetzt. Deren führende Leerzeichen werden entfernt. Ein fortgesetzter Wert wird beim Zurückschreiben in einer einzigen Zeile gespeichert. - Escape-Sequenzen.
\uXXXX,\t,\n,\r,\f,\=,\:,\,\\und alle anderen maskierten Zeichen werden vor der Übersetzung dekodiert. Eine fehlerhafte\u-Escape-Sequenz führt wie in Java dazu, dass die Verarbeitung der Datei fehlschlägt. - Leere Werte. Ein Schlüssel, dessen Wert leer ist oder nur aus Leerzeichen besteht, bleibt unverändert und wird nicht übersetzt. Ein leerer Wert in einer Zieldatei gilt als nicht übersetzt. Ausgenommen sind Schlüssel in
preservedKeys, für die der leere Wert erhalten bleibt.
Die Datei wird als UTF-8 gelesen. Eine in ISO-8859-1 gespeicherte Datei mit nicht maskierten Bytes für Akzentzeichen wird nicht unterstützt. Speichere sie als UTF-8 oder schreibe diese Zeichen als \uXXXX. Eine UTF-8-Byte-Reihenfolgemarkierung am Dateianfang bleibt nicht erhalten.
So werden Übersetzungen geschrieben #
Jeder übersetzte Wert wird so maskiert, dass Java ihn unverändert wieder einliest: Backslashes, Zeilenumbrüche, Tabulatoren, Seitenvorschübe und andere Steuerzeichen sowie ein Leerzeichen, = oder : am Wertanfang. Zeichen außerhalb von ASCII werden entsprechend den bereits in der Datei vorhandenen Werten geschrieben. Kommentare zählen dabei nicht:
| Die Werte der Zieldatei (oder der Quelldatei, solange noch keine Zieldatei existiert) | Zeichen wie é oder 中 werden geschrieben |
|---|---|
| Enthalten bereits nicht maskierten UTF-8-Text | Unverändert |
| Enthalten nur ASCII | Als \u00E9, \u4E2D |
Wenn Werte maskiert werden, gilt das für jeden geschriebenen Wert – auch für gesperrte oder beibehaltene Werte, die in der Quelle nicht maskierten Text enthalten. Eine maskierte Datei lässt sich sowohl mit einem UTF-8-Reader als auch mit Properties.load(InputStream) laden, das ISO-8859-1 liest.
Platzhalter wie {0}, {name} und %s bleiben in der Übersetzung erhalten. Die Regeln für Anführungszeichen in Javas MessageFormat, etwa '' für einen Apostroph in einer Nachricht mit Argumenten zu schreiben, werden nicht automatisch angewendet.
Schlüssel und Text unübersetzt lassen #
lockedKeys, preservedKeys und ignoredKeys gleichen wie die bisherige CLI den gesamten Schlüssel ab: Ein Muster passt zu einem identischen Schlüssel, zu einem Schlüssel, der das Muster nach ., / oder - fortsetzt, oder zu einem Schlüssel, der dem Muster als Glob entspricht. So passt app zu app.title, app.* zu app.title und app.menu.save sowie *.port zu server.port. Ein Muster, das mit $ beginnt, ist stattdessen eine JSONPath-Abfrage über die Schlüssel, etwa $["app.title"].
| Option | Ergebnis in der Zieldatei |
|---|---|
lockedKeys | Der Quellwert; er wird niemals zur Übersetzung gesendet. |
preservedKeys | Der vorhandene Zielwert oder, wenn keiner vorhanden ist, der Quellwert. |
ignoredKeys | Der gesamte Eintrag wird ausgelassen, einschließlich der Fortsetzungszeilen. |
lockedPatterns lässt Teile eines Werts unübersetzt. Jeder Eintrag ist ein regulärer Ausdruck in RE2-Syntax. Jeder Treffer innerhalb eines Werts wird gesperrt, wobei ^ und $ an Zeilenumbrüchen innerhalb eines Werts greifen:
{
"pattern": "src/main/resources/messages_en.properties",
"lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}Ein Treffer wird als Token an das Modell gesendet, das dieses unverändert beibehalten muss, und Byte für Byte zurückgeschrieben. Eine Übersetzung, in der ein Treffer fehlt oder verändert wurde, wird abgelehnt und niemals geschrieben. Muster werden innerhalb jedes einzelnen Werts abgeglichen, nicht über Zeilen, Schlüssel oder Kommentare hinweg. In einem Wert mit einem Treffer werden Platzhalter wie {0} und %s auf dieselbe Weise geschützt.
Die Laufzeit von RE2 ist proportional zur Textlänge. Daher unterstützt es weder Lookaround ((?=, (?!, (?<=, (?<!) noch Rückverweise (\1, \k<name>). Schreibe ein Zeichen außerhalb von ASCII als \x{00E9}, nicht als \u00E9. Die CLI und die GitHub App lehnen beim Lesen der Konfiguration ein Muster ab, das kein regulärer Ausdruck ist. Verwendet ein Muster eine von RE2 nicht unterstützte Syntax, schlägt der Push fehl und nennt das betreffende Muster. lockedPatterns gilt nur für Properties-Dateien: Ein Eintrag in einem anderen Format, der diese Option setzt, wird abgelehnt.
--key beschränkt einen Push auf die darin angegebenen Schlüssel. Der Abgleich erfolgt wie bei lockedKeys.
Wiederverwendung und Korrekturen #
Ein Schlüssel behält seine vorhandene Übersetzung, solange sein Quellwert seit dem letzten Push unverändert ist. Ändert sich ein Quellwert, wird dieser Schlüssel erneut übersetzt. Schlüssel, die nur in einer Zieldatei vorkommen, werden daraus entfernt. Die Zielschlüssel übernehmen die Reihenfolge und das Layout der Quelle.
Ein Push mit --key bearbeitet stattdessen die vorhandene Zieldatei: Nur die ausgewählten Werte ändern sich. Die übrigen Zeilen bleiben unverändert, einschließlich der Kommentare und der Schlüssel, die nur in der Zieldatei vorkommen. Ein ausgewählter Schlüssel, der dort fehlt, wird am Dateiende hinzugefügt.
Um eine einzelne Übersetzung zu korrigieren, bearbeite sie in der Zieldatei. Um sie neu zu erzeugen, führe erneut einen Push mit --key aus:
lingo push --key checkout.title --wait