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).

Formát	Přípony	Hodnota `format`	Poznámky
JSON	`.json`	`json`	Klíč/hodnota. Podporuje řízení podle klíčů.
JSONC	`.jsonc`	`jsonc`	JSON s komentáři. Komentáře zůstávají zachované a zároveň fungují jako poznámky pro překladatele.
YAML	`.yaml`, `.yml`	`yaml`	Obecný YAML. Překládá se každá textová hodnota; klíče i struktura zůstávají zachované.
OpenAPI YAML	`.yaml`, `.yml`	`yaml-openapi`	Specifikace OpenAPI. `format` nastavte výslovně — samotné `.yaml` se automaticky rozpozná jako `yaml`.
YAML s jazykem jako kořenovým klíčem	`.yaml`, `.yml`	`yaml-root-key`	Jazyk je kořenovým klíčem YAML (Rails `config/locales`). Kořenový klíč se přepíše na cílový jazyk. `format` nastavte explicitně.
Markdown	`.md`	`md`	Překládá se běžný text; frontmatter je potřeba zapnout.
MDX	`.mdx`	`mdx`	Markdown + JSX. Props komponent je potřeba zapnout.
Markdoc	`.mdoc`	`markdoc`	Markdown + tagy. Frontmatter + atributy tagů.
TypeScript	`.ts`, `.mts`, `.cts`	`typescript`	Moduly jazyků (`export default { … }`). Řetězcové literály se překládají; kód zůstává zachovaný.
Gettext PO	`.po`	`po`	Překládá se `msgstr`; `msgid`, komentáře i hlavičky zůstávají zachované.
Flutter ARB	`.arb`	`flutter`	Překládají se textové hodnoty; metadata `@` a `{placeholders}` zůstávají zachovaná.
Android	`.xml`	`android`	`strings.xml`. `format` nastavte výslovně — `.xml` se automaticky nerozpozná.
Xcode strings	`.strings`	`xcode-strings`	Hodnoty se překládají; klíče zůstávají zachované.
Xcode String Catalog	`.xcstrings`	`xcode-xcstrings`	Jeden soubor obsahuje všechny jazyky — cílové překlady se zapisují zpět do stejného souboru (viz níže).
Xcode stringsdict	`.stringsdict`	`xcode-stringsdict`	Překládají se plurálové řetězce; řídicí klíče formátu zůstávají zachované.
XLIFF	`.xlf`, `.xliff`	`xliff`	`<source>` zůstává zachované, `<target>` se zapisuje po jednotkách. Verze 1.2 a 2.0.
SubRip	`.srt`	`srt`	Překládá se text titulků; indexy a časové kódy zůstávají beze změny.
PHP	`.php`	`php`	Laravel `return [ … ]`. Překládají se textové hodnoty; klíče, čísla i struktura zůstávají zachované.

Projděte si to od začátku do konce

Ukázkový projekt je malý Sandbox, který pokrývá formáty dokumentů a dat — JSON, JSONC, Markdown, MDX, Markdoc a OpenAPI YAML — každý s přesně takovou konfigurací, jakou potřebuje. Naklonujte ho pomocí npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo a spusťte push. Formáty pro aplikace a frameworky v něm nejsou — pro ně najdete v Example projects plnohodnotný repozitář pro každý framework a níže uvedené ukázky pro jednotlivé formáty pokrývají konfiguraci.

bash

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.

json

{ "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.

json

{ "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:

json

{
  "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:

json

{
  "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ů:

json

{
  "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é:

json

{ "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:

json

{ "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ě:

json

{ "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:

json

{ "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á:

json

{ "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:

json

{ "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.

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í:

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.
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.
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.
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.

Formát	Přípony	Hodnota `format`	Poznámky
JSON	`.json`	`json`	Klíč/hodnota. Podporuje řízení podle klíčů.
JSONC	`.jsonc`	`jsonc`	JSON s komentáři. Komentáře zůstávají zachované a zároveň fungují jako poznámky pro překladatele.
YAML	`.yaml`, `.yml`	`yaml`	Obecný YAML. Překládá se každá textová hodnota; klíče i struktura zůstávají zachované.
OpenAPI YAML	`.yaml`, `.yml`	`yaml-openapi`	Specifikace OpenAPI. `format` nastavte výslovně — samotné `.yaml` se automaticky rozpozná jako `yaml`.
YAML s jazykem jako kořenovým klíčem	`.yaml`, `.yml`	`yaml-root-key`	Jazyk je kořenovým klíčem YAML (Rails `config/locales`). Kořenový klíč se přepíše na cílový jazyk. `format` nastavte explicitně.
Markdown	`.md`	`md`	Překládá se běžný text; frontmatter je potřeba zapnout.
MDX	`.mdx`	`mdx`	Markdown + JSX. Props komponent je potřeba zapnout.
Markdoc	`.mdoc`	`markdoc`	Markdown + tagy. Frontmatter + atributy tagů.
TypeScript	`.ts`, `.mts`, `.cts`	`typescript`	Moduly jazyků (`export default { … }`). Řetězcové literály se překládají; kód zůstává zachovaný.
Gettext PO	`.po`	`po`	Překládá se `msgstr`; `msgid`, komentáře i hlavičky zůstávají zachované.
Flutter ARB	`.arb`	`flutter`	Překládají se textové hodnoty; metadata `@` a `{placeholders}` zůstávají zachovaná.
Android	`.xml`	`android`	`strings.xml`. `format` nastavte výslovně — `.xml` se automaticky nerozpozná.
Xcode strings	`.strings`	`xcode-strings`	Hodnoty se překládají; klíče zůstávají zachované.
Xcode String Catalog	`.xcstrings`	`xcode-xcstrings`	Jeden soubor obsahuje všechny jazyky — cílové překlady se zapisují zpět do stejného souboru (viz níže).
Xcode stringsdict	`.stringsdict`	`xcode-stringsdict`	Překládají se plurálové řetězce; řídicí klíče formátu zůstávají zachované.
XLIFF	`.xlf`, `.xliff`	`xliff`	`<source>` zůstává zachované, `<target>` se zapisuje po jednotkách. Verze 1.2 a 2.0.
SubRip	`.srt`	`srt`	Překládá se text titulků; indexy a časové kódy zůstávají beze změny.
PHP	`.php`	`php`	Laravel `return [ … ]`. Překládají se textové hodnoty; klíče, čísla i struktura zůstávají zachované.

Projděte si to od začátku do konce

bash

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.

json

{ "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.

json

{ "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:

json

{
  "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:

json

{
  "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ů:

json

{
  "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é:

json

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

json

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

json

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

Formáty aplikací a frameworků#

json

{ "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á:

json

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

Xcode String Catalogs#

json

{ "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.

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í:

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.
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.
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.
String Catalog, kde cílová cesta je zdrojová cesta, protože jeden soubor obsahuje všechny jazyky.