Konfigurace CLI
Nastavte vyhledávání zdrojů, možnosti překladu a cílové cesty v .lingo/config.json.
.lingo/config.json určuje, které soubory projekt překládá a kam patří jejich cílové verze. CLI hledá nejbližší konfiguraci od pracovního adresáře směrem k nadřazeným adresářům a od jejího kořene odvozuje cesty relativní k projektu. Pokud konfigurace neexistuje, lokální příkazy pro práci s katalogem používají cwd.
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "locales/en.json" }]
}Spuštěním link přidejte ID organizace a lokalizačního engine pro vzdálený překlad. Extrakce může nastavení i18n používat lokálně i bez těchto ID. Dodržujte striktní syntaxi JSON: komentáře ani čárky za poslední položkou zde nejsou povoleny.
Pole na kořenové úrovni #
| Pole | Význam |
|---|---|
orgId, engineId | Neprázdná ID prostředků; obě společně definují vzdálené propojení. |
sourceLocale | Neprázdný řetězec určující zdrojový jazyk. |
targetLocales | Položky tvořené neprázdnými řetězci; za běhu se odstraní duplicity a položka přesně odpovídající zdrojovému jazyku. |
files | Zdrojové položky popsané níže. |
i18n.messagesPath | Adresář katalogu pro extrakci, kontrolu a čištění; výchozí hodnota je locales. |
i18n.typesPath | Cesta k deklaraci pro extrakci a kontrolu; výchozí hodnota je lingo.d.ts. |
github.workflows.onPushToDefaultBranch.enabled | Nepovinný spouštěč integrace pro výchozí větev. |
github.workflows.onPullRequest.enabled | Nepovinný spouštěč integrace pro pull requesty. |
github.safety.requireApproval | Nepovinné nastavení schvalování spuštění integrace. |
Neznámé klíče na kořenové úrovni a v položkách souborů vyvolají varování a ignorují se. Kvůli překlepu tak může zůstat v platnosti výchozí hodnota, místo aby byl odmítnut celý soubor.
Příkaz init zapisuje nastavení lokalizace, link zapisuje ID propojení a unlink odstraňuje pouze tato ID. Příkazy při zápisu zachovávají ostatní sekce na kořenové úrovni, ale init --force vytváří položky souborů znovu, takže se pokročilé možnosti ztratí. Nastavení pro GitHub nenainstaluje aplikaci ani nezajistí, aby příkaz push v CLI spouštěl automatizaci repozitáře; použijte nastavení integrace.
Pole položek souborů #
| Pole | Význam |
|---|---|
pattern | Jeden neprázdný vzor pro zdrojové soubory. |
include | Vzory pro zdrojové soubory; mají přednost před pattern, i když je seznam prázdný. |
exclude | Vzory vyloučené z této položky. |
format | Výslovně zadaný formát z níže uvedeného seznamu podporovaných formátů. |
localeFormat | Zápis cesty ve tvaru bcp47, underscore nebo android. |
targetPath, sourceRoot | Výstupní šablona a nepovinná předpona, která se odstraňuje pro [path]. |
translateFrontmatterFields | Pole metadat vybíraná obslužnými moduly pro formáty z rodiny Markdown. |
translateComponentProps | Názvy vlastností nebo pravidla pro vlastnosti filtrovaná podle komponent. |
lockedKeys, preservedKeys, ignoredKeys | Neprázdná pole cest ke klíčům pro obslužné moduly, které je podporují. |
injectLocale | Logická hodnota nebo { "enabled": true, "key": "language" }. |
keyColumn | Pouze CSV: záhlaví sloupce s klíči; ve výchozím nastavení první buňka záhlaví. |
lockedPatterns | Pouze pro soubory properties: regulární výrazy RE2 v hodnotách se nepřekládají. |
Každá položka vyžaduje pattern nebo include; prázdné include nevybere nic. Možnosti určuje první odpovídající položka. Část Řízení klíčů vysvětluje vlastnictví hodnot a hranice formátů.
Vzory souborů #
Vyhledávání shod podporuje * uvnitř segmentu a **/ napříč adresáři. Pro rekurzivní podstrom použijte docs/en/**/*; samotné ** na konci nemá stejný význam. Nepředpokládejte, že složené závorky nebo rozšířené vzory extglob fungují stejně jako v jiné knihovně pro vzory glob.
{
"sourceLocale": "en",
"targetLocales": ["de"],
"files": [
{
"include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
"exclude": ["docs/en/private/**/*"]
}
]
}Vyloučení platí pouze pro danou položku; jiná položka může soubor přesto zahrnout. Vyhledávání přeskakuje .git a node_modules, nikoli vše v .gitignore. Vzory zadané jako poziční argumenty příkazu push dále zužují nakonfigurované zdroje na společný průnik a mění režim plánování. V shellu je uzavřete do uvozovek.
Výběr formátu #
Nastavené formáty jsou json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv a properties.
| Přípona | Odvozený formát |
|---|---|
.json, .jsonc | JSON nebo JSONC. |
.md, .mdx, .mdoc | Markdown, MDX, Markdoc. |
.html, .htm | HTML. |
.po, .arb | Gettext, Flutter. |
.strings, .xcstrings, .stringsdict | Odpovídající formát Apple. |
.ts, .mts, .cts | TypeScript. |
.srt, .xlf, .xliff, .php | SubRip, XLIFF, PHP. |
.txt | Prostý text, pouze pro vzor končící na .txt nebo při nastavení formátu txt. |
.csv | CSV, pouze pro vzor končící na .csv nebo při nastavení formátu csv. |
.properties | Soubory properties pro Javu, pouze pokud vzor končí formátem .properties nebo properties. |
.yaml, .yml | Výslovně nastavte yaml, yaml-root-key nebo OpenAPI založené na yaml. |
.xml | Výslovně nastavte android; obecné XML není podporováno. |
Přesný identifikátor pro OpenAPI je yaml-openapi. I při výslovném výběru formátu platí seznam přípon podporovaných při vyhledávání souborů. Soubor .txt, .csv nebo .properties spadá pouze pod položku, jejíž vzor končí danou příponou nebo která má nastavený odpovídající formát txt, csv nebo properties. Taková položka vybírá pouze soubory s danou příponou. Soubory .js, .tsx, .pot, MJML a VTT nejsou nastaveny jako vstupní soubory CLI. Extrakce z React TSX je samostatná operace.
Překlad HTML nahrazuje vybraný text a atributy přímo v původním zdroji a zachovává nezměněné značky, komentáře i formátování. Výslovně uvedený prvek <html> získá cílový jazyk v atributu lang; fragmenty zůstávají fragmenty. Podrobnosti o výběru textu a podobě výstupu najdete v části HTML.
Část Formáty popisuje chování parseru včetně přeskakovaných struktur a omezení při rekonstrukci. Sdílené serverové obslužné moduly tento výčet formátů CLI nerozšiřují.
Výstupní cesty #
Pokud ze zdrojových cest nelze určit jazyk, použijte výslovně zadanou šablonu:
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [
{
"pattern": "docs/**/*.md",
"sourceRoot": "docs",
"targetPath": "i18n/[locale]/docs/[path]"
}
]
}Z docs/start.md vznikne i18n/de/docs/start.md a i18n/fr/docs/start.md. [locale] používá zápis jazyka nastavený pro danou položku; [path] odstraňuje zdrojový kořen pouze na hranici segmentu. Kořen docs neodstraní část docsite.
Šablony vyžadují [locale]; vstupy se vzory glob vyžadují také [path]. Jiné zástupné symboly nejsou podporovány. Absolutní cesty, .., kořeny se vzory glob, kořeny mimo vstupy a výstupy znovu nalezené jako nakonfigurované zdroje se odmítají. sourceRoot bez targetPath je neplatné. Příkaz push také kontroluje kolize výstupních cest bez rozlišování velikosti písmen.
Příkazy push, pull a purge zohledňují i souborový systém: pokud zdroj, cíl, .lingo/lock.json nebo .lingo/config.json po vyhodnocení cesty směřuje mimo kořen projektu nebo do .git, například přes symbolický odkaz, příkaz skončí chybou dříve, než se tam cokoli přečte, zapíše nebo odstraní. Odkazy vedoucí dovnitř projektu nadále fungují, ale pokud je samotný cíl nebo soubor Lockfile odkazem, zápis přes něj neproběhne. V monorepozitáři spouštějte příkazy z kořene, který obsahuje sdílené soubory, místo abyste na ně vytvářeli odkazy z balíčku.
Bez šablony se cesta odvozuje postupně podle adresáře zdrojového jazyka, celého názvu souboru bez přípony a adresářových struktur dané platformy. Nakonec se vloží adresář jazyka a zobrazí se varování. Příklady zahrnují locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → cílové .lproj a u Androidu values → prostředky s kvalifikátorem jazyka. Čtěte varování a ověřte, že aplikace z daného cílového umístění načítá.
XCStrings a CSV ukládají všechny jazyky do zdrojového souboru a odmítají targetPath. Výstupy pro více jazyků tento soubor záměrně sdílejí; jeho existence nedokazuje, že obsahuje každý jazyk. Vyčištění sdílený soubor přeskakuje, a proto nemůže odstranit položky jednotlivých jazyků.
Výběr metadat a textu komponent #
Pokud tuto možnost vynecháte, překlad formátů z rodiny Markdown vybere z úvodních metadat pole title a description. Prázdný seznam výběr vypne; výslovně zadaný seznam vybere jiná pole. Cesty k vnořeným skalárním hodnotám a polím vyžadují úvodní metadata, která lze zpracovat parserem. Pokud jsou metadata chybná, může se místo toho použít prohledávání na nejvyšší úrovni.
{
"pattern": "docs/en/**/*.mdx",
"translateFrontmatterFields": ["title", "description"],
"translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}Řetězec vybere vlastnost bez filtrování podle komponenty. Objekt vybere props a umožňuje omezit výběr podle názvů komponent. Tato pravidla vybírají přeložitelný obsah zadaný jako literál, nikoli kód komponent ani všechny atributy. Markdown, MDX a Markdoc se liší; při změně cest zkontrolujte příslušný obslužný modul.
Pokyny pro překladatele v JSONC přidáte vložením @context bezprostředně před příslušný řetězec. Obecný výstup JSONC zachovává značky @orphan, ale ostatní komentáře odstraňuje. U metadat @src v Reactu se proto řiďte pravidly pro načítání katalogu a nepředpokládejte, že je příkaz pull zachová.
U dokumentačních frameworků nastavujte skutečné zdrojové a výstupní adresáře nezávisle na směrování. OpenAPI používá yaml-openapi, kořeny jazyků ve stylu Rails používají yaml-root-key a obecný YAML používá yaml. Samotná shoda přípony nestačí k výběru správné sémantiky.
Jazyky #
Konfigurace ověřuje, zda jsou řetězce neprázdné, nikoli zda patří do úplného výčtu jazyků. Používejte identifikátory, které potřebují váš model a aplikace, včetně oblasti nebo písma. localeFormat určuje podobu cest: bcp47 zachovává spojovníky, underscore vytváří pt_BR a android vytváří tvary jako pt-rBR nebo b+zh+Hans. Formát Android používá zápis pro Android, pokud nenastavíte jiný; to ovlivňuje i vyhledávání odpovídajících zdrojů.
Než přidáte cílový jazyk a doplníte jeho chybějící soubory, dokončete všechny nevyřízené běžné aktualizace zdrojů. Část Přidání jazyka vysvětluje, jak toto pořadí udržuje stávající jazyky aktuální. Odebráním cílového jazyka ukončíte jeho budoucí výběr, ale existující soubory se nesmažou. U vložených metadat jazyků a sdílených katalogů je nutné dodržet pravidla příslušného obslužného modulu. Správně zapsaná cesta nezajišťuje směr textu, směrování ani jazykovou kvalitu.
Cesty katalogu #
Při extrakci a kontrole mají výslovně zadané --out/--types přednost před nastavením i18n, po němž následují výchozí hodnoty. Výchozí hodnota --source-locale je en, nezávisle na lokalizačním nastavení sourceLocale. Změna messagesPath neaktualizuje files[]; pro překlad vyberte cestu k vygenerovanému JSONC.
Monorepozitáře #
Kořenová konfigurace umožňuje sdílet jazyky a lokalizační engine napříč balíčky určenými rekurzivními nebo výslovně zadanými cestami. Konfigurace jednotlivých balíčků naopak umožňují udržovat jazyky, konfiguraci a soubory Lockfile nezávisle. Příkazy spouštějte z kořene zamýšleného balíčku, aby vyhledávání nejbližší konfigurace nečekaně nevybralo konfiguraci z nadřazeného adresáře.
Adresářová matice v CI by měla zachovat shromážděný výstup každého projektu a zabránit překrývajícím se zápisům. Ukazatele na spuštění uložené v domovském adresáři závisejí na absolutních cestách ke kořenům a nesdílejí se prostřednictvím souboru Lockfile. lingo check porovnává každý zdroj vybraný pomocí files se souborem Lockfile na úrovni souborů; klíče uvnitř souborů nekontroluje.
Konfigurace hodnocení #
lingo score používá spustitelný soubor lingo.config.ts, který se načítá přes Jiti. Tato konfigurace je oddělená od projektového JSON a neregistruje libovolné lokální zavaděče formátů. Důvěryhodné pluginy pro hodnocení a nastavení vzdálené lokalizace souborů udržujte odděleně.