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:
{
"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:
{
"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\uzpů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-8 | Beze změny |
| Obsahují pouze ASCII | Jako \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žnost | Výsledek v cílovém souboru |
|---|---|
lockedKeys | Zdrojová hodnota, která se nikdy neodesílá k překladu. |
preservedKeys | Stávající cílová hodnota, nebo zdrojová hodnota, pokud cílová chybí. |
ignoredKeys | Celá 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:
{
"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:
lingo push --key checkout.title --wait