Zprávy a kontext
Pište úplné zdrojové zprávy, vysvětlete jejich význam a vkládejte proměnlivé hodnoty, aniž by se měnila identita zpráv.
Aby překlad zachoval zamýšlenou akci nebo význam zprávy, potřebuje dostatek informací. Napište úplný zdrojový text a v context vysvětlete, k čemu slouží. Jména, počty a další proměnlivé údaje předávejte prostřednictvím values.
import { useLingo } from "@lingo.dev/react";
export function Greeting({ name }: { name: string }) {
const l = useLingo();
return (
<h1>
{l.text("Welcome back, {name}.", {
context: "Greeting at the top of the account dashboard",
values: { name },
})}
</h1>
);
}Výsledkem je řetězec. TextOptions vyžaduje context: string a přijímá values?: Record<string, string | number>. Katalog obsahuje šablonu věty; v překladu lze {name} přesunout na místo, které vyžaduje gramatika daného jazyka.
Vysvětlete význam nejednoznačné zprávy #
„Save“ může znamenat odeslání formuláře nebo uložení článku do záložek. Díky kontextu jde o dvě samostatné zprávy, přestože mají totožný anglický zdrojový text:
import { computeKey } from "@lingo.dev/react";
const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");Klíče se liší. Překladatel tak může pro každou akci zvolit správné sloveso. Kontext typu „Text zobrazený uživateli“ tuto nejednoznačnost neřeší. Popište akci, cílovou skupinu nebo omezení, které mohou ovlivnit formulaci.
Extraktor tyto informace zapíše do komentáře @context v katalogu. Slouží jako vodítko pro překlad, nikoli jako viditelný text rozhraní. Opakovaně používanou terminologii, instrukce a požadavky na styl komunikace ukládejte do kontextu překladu lokalizačního engine. Význam konkrétní zprávy ponechte u příslušného volání.
Identita zprávy #
computeKey(source: string, context?: string): string generuje ze zdrojového textu a kontextu osmiznakový klíč. Neprázdný kontext připojí ke zdrojovému textu pomocí oddělovače v podobě nulového znaku, spojený vstup normalizuje do formy Unicode NFC a vypočítá hash jeho bajtů v UTF-8.
Kanonicky ekvivalentní zápisy v Unicode mají stejný klíč. Změna formulace, interpunkce, velikosti písmen, bílých znaků nebo kontextu může vytvořit nový klíč. Hodnoty do výpočtu hashe nevstupují, takže všechna jména v pozdravu využívají stejnou položku zprávy.
Po změně zdrojového textu nebo kontextu spusťte extrakci znovu a zkontrolujte nové i osiřelé položky. Pokud překlad zkopírujete pod nový klíč bez kontroly významu, můžete zachovat právě tu formulaci, kterou měla změna zdrojového textu nahradit. Počet možných hashů je konečný; extraktor odhaluje kolize mezi zprávami, které shromáždí.
Pište volání tak, aby je bylo možné extrahovat #
Ve voláních, jako je l.text(...), zapisujte zdrojový text i kontext jako řetězcové literály. Běhové prostředí může přijmout vypočítaný řetězec, extraktor ale nedokáže odvodit všechny řetězce, které by program mohl sestavit. Jako příjemce volání používejte l nebo podporovanou proměnnou vytvořenou pomocí useLingo či createLingo. Rozpoznávané podoby volání popisuje reference příkazu extract.
Pro proměnlivé údaje používejte zástupné symboly namísto generování zdrojových řetězců, jako je "Welcome, " + name. Stabilní šablonu lze extrahovat, jednou přeložit pro každý význam a opakovaně používat s různými hodnotami.
Interpolace a ICU #
Jednoduché zástupné symboly používají názvy jako {name}. Předané hodnoty se převedou na text. Zástupné symboly, pro které hodnota chybí, zůstanou viditelné. Pokud objekt values vynecháte, vrátí se vybraná šablona bez interpolace.
Pro gramatické tvary, které závisejí na množství nebo kategorii, podporuje formátovač textu komplexní vzory ICU prostřednictvím intl-messageformat:
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
context: "Number of files attached to a message",
values: { count: 0 },
});Výsledkem je No files. Explicitní větev =0 odlišuje nulu od běžných kategorií množného čísla daného jazyka. Předejte všechny argumenty, které vybraná šablona potřebuje. Pokud parsování nebo formátování komplexního vzoru ICU selže, běhové prostředí vrátí danou šablonu a ohlásí chybu pro vývojáře bez duplicitních hlášení. Chybný překlad nenahradí nově naformátovaným zdrojovým textem.
Množná čísla a výběry nabízejí pomocné funkce pro úplné alternativy. Formátovaný text vkládá prvky React pomocí samostatného parseru pojmenovaných značek. Používejte odpovídající formu a nemíchejte komplexní výrazy ICU do šablon formátovaného textu.