Soubory Java properties

Překládejte balíčky prostředků Java .properties po jednotlivých klíčích a zachovejte komentáře, prázdné řádky i rozvržení každého řádku.

Soubor .properties přiřazuje klíčům zprávy, vždy jednu položku na řádek, jak je čtou ResourceBundle v Javě a MessageSource ve Springu. Obslužný modul pro soubory properties přeloží hodnotu každého klíče a zapíše ji do kopie zdrojového souboru. Komentáře, prázdné řádky, pořadí klíčů, oddělovače i mezery zůstanou beze změny. Změní se pouze hodnota přeloženého klíče.

Nastavení překladu souborů properties #

Soubor properties může spadat pouze pod položku konfigurace souborů, jejíž vzor končí na .properties a formát se tak odvodí automaticky, nebo pod položku s nastavením "format": "properties". Položka s "format": "properties" vybírá pouze soubory .properties. Obecný vzor jako src/main/resources/**/* bez nastavení tohoto formátu soubor properties nikdy nevybere, takže se konfigurační soubory jako application.properties nepřeloží omylem.

Pokud název souboru obsahuje jazyk, například messages_en.properties, každý cílový soubor se vytvoří vedle něj a označení cílového jazyka bude v názvu na stejném místě. Jazyky se zapisují ve formátu Javy s podtržítkem, pt_BR, který při vyhledávání používá ResourceBundle:

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

Tím se vytvoří soubory messages_de.properties a messages_pt_BR.properties. Stejně se vyhledá i regionální varianta zdrojového jazyka: při "sourceLocale": "en-US" je zdrojem messages_en_US.properties. Chcete-li použít jiný zápis, nastavte u položky localeFormat, například "bcp47" pro pt-BR. Pokud je zdrojem výchozí balíček messages.properties bez označení jazyka v názvu, uveďte cílovou cestu:

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

Stejná konfigurace funguje v CLI i v GitHub App.

Jak se soubor čte #

Klíče a hodnoty se čtou stejně, jako je čte java.util.Properties:

  • Jednotky. Každý klíč tvoří jednu jednotku. Klíč, který se vyskytuje dvakrát, se přeloží jen jednou, a to s hodnotou, kterou načte Java, tedy s tou poslední. Překlad se zapíše do všech jeho výskytů.
  • Oddělovače. Klíč od hodnoty odděluje =, : nebo bílý znak. Kolem = a : mohou být mezery.
  • Komentáře a prázdné řádky. Řádek, jehož první znak po vynechání úvodních bílých znaků je # nebo !, je komentář. Komentáře ani prázdné řádky se nikdy neodesílají k překladu.
  • Pokračování řádků. Řádek zakončený \ pokračuje na dalším řádku, jehož úvodní mezery se vynechají. Takto rozdělená hodnota se zapíše zpět na jediný řádek.
  • Escape sekvence. \uXXXX, \t, \n, \r, \f, \=, \:, \ , \\ i jakýkoli jiný escapovaný znak se před překladem dekódují. Chybně zapsaná escape sekvence \u způsobí selhání zpracování souboru, stejně jako v Javě.
  • Prázdné hodnoty. Klíč s prázdnou hodnotou nebo hodnotou tvořenou pouze mezerami se ponechá beze změny a nepřekládá se. Prázdná hodnota v cílovém souboru se považuje za nepřeloženou, s výjimkou klíče v preservedKeys, u kterého se zachová.

Soubor se čte v kódování UTF-8. Soubory uložené v ISO-8859-1 s přímo zapsanými bajty znaků s diakritikou nejsou podporovány. Uložte soubor v UTF-8 nebo tyto znaky zapište jako \uXXXX. Značka pořadí bajtů UTF-8 na začátku souboru se nezachová.

Jak se překlady zapisují #

Každá přeložená hodnota se escapuje tak, aby ji Java znovu načetla beze změny: escapují se zpětná lomítka, zalomení řádků, tabulátory, posuny stránek a další řídicí znaky, stejně jako mezera, = nebo : na začátku hodnoty. Způsob zápisu znaků mimo ASCII se řídí hodnotami, které už soubor obsahuje. Komentáře se neberou v úvahu:

Hodnoty v cílovém souboru (nebo ve zdrojovém, pokud ještě žádný cílový neexistuje)Znaky jako é nebo 中 se zapisují
Již obsahují přímo zapsaný text v UTF-8Beze změny
Obsahují pouze ASCIIJako \u00E9, \u4E2D

Při escapování hodnot se escapuje každá zapisovaná hodnota, včetně uzamčené nebo zachované hodnoty, která ve zdroji obsahuje přímo zapsaný text. Escapovaný soubor lze načíst jak čtečkou UTF-8, tak pomocí Properties.load(InputStream), které čte v kódování ISO-8859-1.

Zástupné symboly jako {0}, {name} a %s se v překladu zachovají. Pravidla pro uvozování ve třídě MessageFormat v Javě, například zápis '' pro apostrof ve zprávě s argumenty, se neuplatňují automaticky.

Ponechání klíčů a textu bez překladu #

lockedKeys, preservedKeys a ignoredKeys porovnávají celý klíč stejně jako dřívější CLI: vzoru odpovídá klíč, který je s ním shodný, klíč, který za ním pokračuje znakem ., / nebo -, nebo klíč odpovídající vzoru se zástupnými znaky. Vzoru app tedy odpovídá app.title, vzoru app.* odpovídají app.title a app.menu.save a vzoru *.port odpovídá server.port. Vzor začínající na $ se místo toho vyhodnotí jako dotaz JSONPath nad klíči, například $["app.title"].

MožnostVýsledek v cílovém souboru
lockedKeysZdrojová hodnota, která se nikdy neodesílá k překladu.
preservedKeysStávající cílová hodnota, nebo zdrojová hodnota, pokud cílová chybí.
ignoredKeysCelá položka se vynechá, včetně navazujících řádků.

lockedPatterns ponechává části hodnoty bez překladu. Každá položka je regulární výraz v syntaxi RE2 a každá shoda v jednotlivých hodnotách se uzamkne. ^ a $ přitom odpovídají pozicím u zalomení řádků uvnitř hodnoty:

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

Nalezená shoda se modelu odešle jako token, který musí zachovat, a zapíše se zpět přesně bajt po bajtu. Překlad, ve kterém shoda chybí nebo je změněná, se odmítne a nikdy se nezapíše. Vzory hledají shody uvnitř jednotlivých hodnot, nikoli napříč řádky, klíči nebo komentáři. V hodnotě s nalezenou shodou se stejným způsobem chrání i zástupné symboly jako {0} a %s.

RE2 pracuje v čase úměrném délce textu, a proto nepodporuje dopředné ani zpětné kontroly okolí ((?=, (?!, (?<=, (?<!) ani zpětné reference (\1, \k<name>). Znak mimo ASCII zapište jako \x{00E9}, nikoli \u00E9. CLI i GitHub App při načítání konfigurace odmítnou vzor, který není regulárním výrazem. Pokud vzor používá syntaxi, kterou RE2 nepodporuje, odeslání selže a chybová zpráva uvede daný vzor. lockedPatterns platí pouze pro soubory properties: položka jiného formátu s tímto nastavením se odmítne.

--key omezí odeslání na uvedené klíče. Používá stejná pravidla porovnávání jako lockedKeys.

Opětovné použití a opravy #

Klíč si ponechá stávající překlad, pokud se jeho zdrojová hodnota od posledního odeslání nezměnila. Když se zdrojová hodnota změní, klíč se přeloží znovu. Klíče, které existují pouze v cílovém souboru, se z něj odstraní. Pořadí a rozvržení klíčů v cílovém souboru se řídí zdrojem.

Odeslání s --key místo toho upraví stávající cílový soubor: změní se pouze vybrané hodnoty. Ostatní řádky cílového souboru, včetně klíčů, které existují jen v něm, i komentářů zůstanou beze změny. Vybraný klíč, který v cílovém souboru chybí, se přidá na jeho konec.

Chcete-li opravit jeden překlad, upravte jej v cílovém souboru. Chcete-li jej vygenerovat znovu, znovu jej odešlete s --key:

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