Lokalizace statického obsahu

Lingo.dev CLI překládá statické soubory ve vašem repozitáři – Markdown, MDX, Markdoc, JSON, YAML, titulky a další – přes nakonfigurovaný lokalizační engine. Stačí ho nasměrovat na váš obsah, spustit a přeložené soubory se objeví vedle zdrojových.

Podporované typy obsahu#

CLI rozpozná formát každého souboru podle přípony — není potřeba nastavovat žádný typ bucketu. Jazyk je součástí cesty (content/en/x.md se změní na content/de/x.md), takže není potřeba zástupný symbol [locale].

Typ obsahu	Formát	Příklad cesty
Dokumentace	Markdown	`docs/en/getting-started.md`
Dokumentace	MDX	`docs/en/getting-started.mdx`
Dokumentace	Markdoc	`docs/en/getting-started.mdoc`
Strukturovaná data	JSON	`data/en.json`
Strukturovaná data	YAML	`data/en.yaml`
Blogové články	Markdown / MDX	`blog/en/post-slug.md`
Lokalizace	Gettext PO	`locale/en/messages.po`
Lokalizace	XLIFF	`locale/en.xliff`
Titulky	SRT	`subs/en/intro.srt`

Úplný seznam podporovaných typů souborů najdete v referenci formátů.

Nové CLI zatím nepodporuje

CSV (csv-per-locale), titulky VTT, prostý text .txt ani Java .properties nový CLI zatím nepodporuje. Tyto soubory proto prozatím ponechte ve starším CLI a sledujte přehled změn, kde najdete novinky.

Předpoklady#

Při každém spuštění prochází obsah přes lokalizační engine – konfiguraci, která určuje, jaký model LLM, glosář, hlas značky a pravidla se použijí. Vytvořte si ho v dashboardu Lingo.dev a pak nastavte CLI (Node 22+):

bash

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

lingo init a lingo link vytvoří .lingo/config.json, který propojí CLI s vaší organizací a enginem. Commitněte tento soubor, aby všechna prostředí sdílela stejnou konfiguraci.

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "docs/en/getting-started.md" }]
}

V CI přeskočte lingo login a místo něj zadejte LINGO_API_KEY jako proměnnou prostředí. Vygenerujete ho v API keys.

Dokumentační weby#

Většina dokumentačních frameworků organizuje přeložený obsah do adresářů podle jazyků. Do files přidejte vzor pro každý zdrojový soubor (nebo glob). CLI při překladu Markdownu, MDX a Markdocu zachová frontmatter, bloky kódu i syntaxi komponent.

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "docs/en/getting-started.md" },
    { "pattern": "docs/en/setup.mdx" }
  ]
}

Spusťte první překlad a doplňte všechny cílové jazyky:

bash

lingo push --backfill-missing

Při dalších spuštěních lingo push přeloží jen to, co se změnilo. Pomocí lingo pull načtete překlady vytvořené jinde.

Upravte zdrojovou cestu tak, aby odpovídala adresářové konvenci vašeho frameworku:

Framework	Konvence adresářů podle jazyka	Reference
Docusaurus	`i18n/[locale]/docusaurus-plugin-content-docs/current/`	Docusaurus i18n guide
Nextra	Stránky podle jazyka nebo JSON slovníky	Nextra documentation
Hugo	`content/[locale]/`	Hugo multilingual guide
Astro	`src/content/[locale]/` nebo JSON slovníky	Astro i18n guide
VitePress	Prefix adresáře `[locale]/`	VitePress i18n
MkDocs	Samostatné `docs/` pro každý jazyk s i18n pluginem	MkDocs i18n plugin

MDX komponenty

Překlad MDX zachovává syntaxi JSX komponent. Vlastní komponenty jako <Callout>, <Tabs> a <CodeBlock> zůstanou beze změny — přeloží se jen textový obsah uvnitř nich.

Strukturovaná data#

Soubory JSON a YAML se překládají automaticky podle přípony. Pomocí key controls zabráníte úpravám nepřeložitelných hodnot (ID, URL, konfigurační příznaky).

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "content/en.json" },
    { "pattern": "data/en.yaml" }
  ]
}

Obecný YAML pole format nepotřebuje. Pouze yaml-openapi, yaml-root-key a android vyžadují v položce souboru explicitní "format".

YAML s kořenovým klíčem jazyka

Soubory YAML, které jako kořenový klíč používají kód jazyka (běžné v Rails a Hugo), vyžadují explicitní "format": "yaml-root-key" — kořenový klíč se přepíše na cílový jazyk. Viz Reference formátů.

Titulky#

SRT titulky se překládají podle přípony. CLI zachovává všechny časové údaje, indexy titulků i formátovací tagy — překládá se pouze textový obsah.

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "subs/en/intro.srt" }]
}

VTT zatím není podporováno

Nové CLI zatím nepodporuje titulky WebVTT (.vtt). Soubory VTT zatím ponechte v legacy CLI a sledujte changelog kvůli novinkám.

Práce s rozsáhlým obsahem#

Repozitáře se statickým obsahem mohou obsahovat tisíce souborů. CLI si s tím poradí efektivně:

Mechanismus	Jak pomáhá
Stav běhu	`.lingo/lock.json` sleduje otisky zdrojového obsahu, takže `lingo push` překládá jen nové nebo upravené soubory. Commitněte ho; při každém pushi se znovu vygeneruje.
Paralelizace na straně serveru	Engine překlad paralelizuje za vás — není potřeba ladit žádný parametr souběžnosti.
Cílená spuštění	Omezte běh na konkrétní soubory pomocí globu: `lingo push "docs/en/**"`.

Chcete-li ověřit, že jsou překlady aktuální, aniž by se zapisovaly soubory — což se hodí jako CI gate — spusťte lingo check.

Další kroky#

Podporované formáty

Kompletní reference všech formátů souborů, které CLI umí překládat

Ukázkové projekty

Funkční repozitáře pro Markdown, MDX, Markdoc a OpenAPI s commitnutou konfigurací i překlady

Key Controls

Zabraňte překladu konkrétních hodnot

GitHub App

Automatizujte překlad statického obsahu při každém pushi

Stav běhu

Jak funguje sledování přírůstkových překladů pomocí .lingo/lock.json

Podporované typy obsahu#

Typ obsahu	Formát	Příklad cesty
Dokumentace	Markdown	`docs/en/getting-started.md`
Dokumentace	MDX	`docs/en/getting-started.mdx`
Dokumentace	Markdoc	`docs/en/getting-started.mdoc`
Strukturovaná data	JSON	`data/en.json`
Strukturovaná data	YAML	`data/en.yaml`
Blogové články	Markdown / MDX	`blog/en/post-slug.md`
Lokalizace	Gettext PO	`locale/en/messages.po`
Lokalizace	XLIFF	`locale/en.xliff`
Titulky	SRT	`subs/en/intro.srt`

Úplný seznam podporovaných typů souborů najdete v referenci formátů.

Nové CLI zatím nepodporuje

Předpoklady#

bash

npm install -g @lingo.dev/cli
lingo login
lingo init
lingo link

lingo init a lingo link vytvoří .lingo/config.json, který propojí CLI s vaší organizací a enginem. Commitněte tento soubor, aby všechna prostředí sdílela stejnou konfiguraci.

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "docs/en/getting-started.md" }]
}

V CI přeskočte lingo login a místo něj zadejte LINGO_API_KEY jako proměnnou prostředí. Vygenerujete ho v API keys.

Dokumentační weby#

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "docs/en/getting-started.md" },
    { "pattern": "docs/en/setup.mdx" }
  ]
}

Spusťte první překlad a doplňte všechny cílové jazyky:

bash

lingo push --backfill-missing

Při dalších spuštěních lingo push přeloží jen to, co se změnilo. Pomocí lingo pull načtete překlady vytvořené jinde.

Upravte zdrojovou cestu tak, aby odpovídala adresářové konvenci vašeho frameworku:

Framework	Konvence adresářů podle jazyka	Reference
Docusaurus	`i18n/[locale]/docusaurus-plugin-content-docs/current/`	Docusaurus i18n guide
Nextra	Stránky podle jazyka nebo JSON slovníky	Nextra documentation
Hugo	`content/[locale]/`	Hugo multilingual guide
Astro	`src/content/[locale]/` nebo JSON slovníky	Astro i18n guide
VitePress	Prefix adresáře `[locale]/`	VitePress i18n
MkDocs	Samostatné `docs/` pro každý jazyk s i18n pluginem	MkDocs i18n plugin

MDX komponenty

Překlad MDX zachovává syntaxi JSX komponent. Vlastní komponenty jako <Callout>, <Tabs> a <CodeBlock> zůstanou beze změny — přeloží se jen textový obsah uvnitř nich.

Strukturovaná data#

Soubory JSON a YAML se překládají automaticky podle přípony. Pomocí key controls zabráníte úpravám nepřeložitelných hodnot (ID, URL, konfigurační příznaky).

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [
    { "pattern": "content/en.json" },
    { "pattern": "data/en.yaml" }
  ]
}

Obecný YAML pole format nepotřebuje. Pouze yaml-openapi, yaml-root-key a android vyžadují v položce souboru explicitní "format".

YAML s kořenovým klíčem jazyka

Titulky#

SRT titulky se překládají podle přípony. CLI zachovává všechny časové údaje, indexy titulků i formátovací tagy — překládá se pouze textový obsah.

json

{
  "orgId": "org_abc123",
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "subs/en/intro.srt" }]
}

VTT zatím není podporováno

Nové CLI zatím nepodporuje titulky WebVTT (.vtt). Soubory VTT zatím ponechte v legacy CLI a sledujte changelog kvůli novinkám.

Práce s rozsáhlým obsahem#

Repozitáře se statickým obsahem mohou obsahovat tisíce souborů. CLI si s tím poradí efektivně:

Mechanismus	Jak pomáhá
Stav běhu	`.lingo/lock.json` sleduje otisky zdrojového obsahu, takže `lingo push` překládá jen nové nebo upravené soubory. Commitněte ho; při každém pushi se znovu vygeneruje.
Paralelizace na straně serveru	Engine překlad paralelizuje za vás — není potřeba ladit žádný parametr souběžnosti.
Cílená spuštění	Omezte běh na konkrétní soubory pomocí globu: `lingo push "docs/en/**"`.

Chcete-li ověřit, že jsou překlady aktuální, aniž by se zapisovaly soubory — což se hodí jako CI gate — spusťte lingo check.

Další kroky#

Podporované formáty

Kompletní reference všech formátů souborů, které CLI umí překládat

Ukázkové projekty

Funkční repozitáře pro Markdown, MDX, Markdoc a OpenAPI s commitnutou konfigurací i překlady

Key Controls

Zabraňte překladu konkrétních hodnot

GitHub App

Automatizujte překlad statického obsahu při každém pushi

Stav běhu

Jak funguje sledování přírůstkových překladů pomocí .lingo/lock.json