Formáty

CLI překládá osmnáct formátů souborů. Formát se určuje podle přípony souboru; pokud ho chcete přepsat, nastavte format v položce files[] — stejně tak u tří formátů, které ji vyžadují vždy (yaml-openapi, yaml-root-key, android).

npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo
cd my-lingo-demo

JSON a JSONC#

Jednoduchý překlad klíč/hodnota. Překládá se každá textová hodnota, pokud řízení podle klíčů neříká jinak.

{ "pattern": "content/en/app.json", "lockedKeys": ["meta.version"] }

JSONC navíc zachovává komentáře, které engine čte jako kontext — viz poznámky pro překladatele.

{ "pattern": "content/en/settings.jsonc", "preservedKeys": ["featureFlags"] }

Markdown, MDX a Markdoc#

Text v obsahu se standardně překládá. Frontmatter a vložené komponenty se nepřekládají, dokud je výslovně nepovolíte.

Frontmatter#

Pole frontmatteru, která se mají překládat, vypište pomocí translateFrontmatterFields:

{
  "pattern": "content/en/guide.md",
  "translateFrontmatterFields": ["title", "description"]
}

Props komponent v MDX#

V MDX můžete pomocí translateComponentProps překládat konkrétní props u konkrétních komponent:

{
  "pattern": "content/en/landing.mdx",
  "translateFrontmatterFields": ["title"],
  "translateComponentProps": [{ "component": ["Hero", "Callout"], "props": ["title", "body"] }]
}

Tím přeložíte props title a body u <Hero> a <Callout>; všechny ostatní props zůstanou beze změny.

Markdoc#

Markdoc funguje stejně jako Markdown, jen se zachováním frontmatteru a atributů tagů:

{
  "pattern": "content/en/changelog.mdoc",
  "translateFrontmatterFields": ["title"]
}

YAML#

Obecný YAML se automaticky rozpozná podle .yaml/.yml — přeloží se každá textová hodnota, klíče i struktura zůstanou zachované:

{ "pattern": "content/en/strings.yaml" }

Specifikace OpenAPI jsou speciální případ: sdílejí příponu .yaml, ale vyžadují výslovné format, aby engine překládal jen pole určená pro uživatele (shrnutí, popisy) a ponechal klíče schémat, cesty a ID operací beze změny:

{ "pattern": "content/en/api.yaml", "format": "yaml-openapi" }

Soubory s jazykem ve stylu Rails jsou dalším speciálním případem: jazyk je kořenovým klíčem YAML (en:) a cílový soubor musí mít jako kořen cílový jazyk (es:). I v tomto případě nastavte format explicitně:

{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" }

Formáty aplikací a frameworků#

PO, Flutter ARB, Xcode .strings, Xcode .stringsdict, moduly jazyků v TypeScriptu, XLIFF, SubRip a PHP se řídí stejným pravidlem: přeložitelný text se překládá, vše strukturální zůstává zachované (klíče, ID, metadata, zástupné symboly, časové kódy, kód, formátování). Každý z nich se automaticky rozpozná podle přípony — stačí pattern nasměrovat na zdrojový soubor:

{ "pattern": "lib/l10n/app_en.arb" }
{ "pattern": "locales/en.po" }
{ "pattern": "Localizable.strings" }
{ "pattern": "l10n/en.xlf" }

Jeden z nich vyžaduje výslovné format, protože jeho přípona je pro automatické rozpoznání příliš nejednoznačná:

{ "pattern": "res/values/strings.xml", "format": "android" }

Xcode String Catalogs#

Soubor .xcstrings (String Catalog) obsahuje všechny jazyky v jednom souboru. Neexistuje žádná výstupní cesta pro jednotlivé jazyky — CLI načte zdrojový jazyk a všechny cílové zapíše zpět do stejného souboru:

{ "pattern": "Localizable.xcstrings" }

Řetězce označené v katalogu jako "shouldTranslate": false se přeskočí — CLI je ponechá nepřeložené a beze změny.

Které formáty podporují rozsah klíčů?#

lingo push --key znovu přeloží jen pojmenované klíče a nic navíc. Potřebuje klíče, které fungují jako stabilní názvy, a soubor, ve kterém klíč může jednoduše chybět. To vylučuje dokumentové formáty i slovníky množných čísel:

U md, mdx, markdoc, html, srt a yaml-openapi se jednotka určuje podle své pozice v dokumentu — pořadí sekce, cesty k uzlu nebo čísla titulkového úseku. Její klíč se tak změní, jakmile se upraví cokoli nad ní, a rozsah cílený na jednu z nich by vybral buď nesprávný řetězec, nebo žádný. xcode-stringsdict se naopak odmítá z opačného důvodu: jeho klíče jsou kategorie množného čísla, které soubor potřebuje, aby zůstal platným slovníkem množných čísel, takže je nikdy nelze vynechat.

lingo push při spuštění omezeném na klíče odmítnuté soubory pouze přeskočí a vypíše upozornění, místo aby celé spuštění selhalo. Push je tak stále může kombinovat se soubory klíč–hodnota; odešlete je bez --key.

Stejně se chovají i poziční položky uvnitř podporovaných formátů a při použití rozsahu si ponechávají zdrojový text: prvky pole, položky Android <string-array> a množství <plurals>.

Výstupní cesty#

Vzor určuje váš zdrojový soubor; všechny cílové cesty se od něj odvozují. Platí čtyři pravidla v tomto pořadí:

1. Celý segment cesty nebo název souboru odpovídá jazyku — to je nejběžnější případ. content/en/app.json → content/de/app.json, locales/en.json → locales/de.json.
2. Jazyk na konci segmentu nebo názvu souboru, u rozvržení, která se zapisují tímto způsobem — Android, Xcode .strings/.stringsdict, Flutter a yaml-root-key. res/values-en/ → res/values-de/, app_en.arb → app_de.arb, devise.en.yml → devise.de.yml.
3. Vyhrazený název platformy pro výchozí jazyk, bez jakéhokoli jazyka v cestě. U Androidu se prosté res/values/ změní na res/values-de/ a u Xcode se Base.lproj změní na de.lproj.
4. String Catalog, kde cílová cesta je zdrojová cesta, protože jeden soubor obsahuje všechny jazyky.

Android je jediná platforma, jejíž cílové cesty nepoužívají BCP 47: CLI zapisuje kvalifikátor prostředků, který Android skutečně čte, takže pt-BR skončí v values-pt-rBR/ a zh-Hans v values-b+zh+Hans/.

Pokud neodpovídá žádné z pravidel — zdrojový jazyk se v cestě nikde neobjevuje — CLI jako záložní řešení vytvoří vedle souboru adresář <locale>/ a lingo push vás upozorní, že šlo o odhad. Berte tohle varování jako signál, že vzor není správně. Viz Configuration.

Přecházíte z legacy CLI?#

Většina formátů z legacy CLI už je v aktuálním CLI k dispozici (PO, XLIFF, Android/Xcode strings, Flutter ARB a další — viz tabulka výše). Několik méně běžných formátů (např. CSV, HTML, MJML, .properties) zatím podporované není; dokud se nepřidá i ten váš, najdete ho v dokumentaci k legacy CLI.