Ovládání klíčů

Ve většině případů chcete přeložit každý řetězec v souboru. Pro výjimky — názvy značek, feature flagy, právní texty nebo interní balast — nabízí CLI tři ovládací prvky na úrovni souboru, které nastavíte v položce files[] v .lingo/config.json.

Všechny tři pracují s cestami ke klíčům v tečkové/závorkové notaci, která odpovídá struktuře souboru:

{
  "files": [
    {
      "pattern": "content/en/app.json",
      "lockedKeys": ["meta.version"],
      "preservedKeys": ["legal.terms"],
      "ignoredKeys": ["internal.debug"]
    }
  ]
}

Uzamknout — zachovat stejnou hodnotu všude#

lockedKeys zkopíruje zdrojovou hodnotu do každého cílového souboru bez překladu. Hodí se pro hodnoty, které musí zůstat naprosto identické napříč jazyky:

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

de.json a fr.json dostanou meta.version s přesným zdrojovým řetězcem. Jakmile zdroj změníte, další lingo push propíše novou hodnotu do všech jazyků — pořád bez překladu.

Zachovat — chraňte ručně napsaný cíl#

preservedKeys říká engine, aby nikdy nepřepsal cílovou hodnotu, která už existuje. Použijte ho ve chvíli, kdy klíč potřebuje lidský překlad — právní text, compliance sdělení nebo cokoli, co jste zkontrolovali a nechcete, aby na to model sahal:

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

Engine při prvním překladu doplní klíč ze zdroje a při všech dalších spuštěních už vaše úpravy nechá být. Srovnejte to s overrides níže.

Ignorovat — vyřaďte klíč z výstupu#

ignoredKeys klíč z cílových souborů úplně odstraní — nepřeloží ho, nezkopíruje ani nezapíše. Použijte ho pro ladicí řetězce, interní flagy a testovací data, která by se nikdy neměla dostat do přeloženého buildu:

{
  "pattern": "content/en/app.json",
  "ignoredKeys": ["internal.debug", "dev.testData"]
}

Overrides vs. zachovat#

Existující cílová hodnota může jedno spuštění přežít dvěma způsoby:

• Zachovat (preservedKeys) — deklarativně. Klíč chrání konfigurace, v každém jazyce a napořád.
• Místní úpravy — lingo push porovnává hash každého cíle s lockfile. Pokud jste cílový soubor upravili ručně, push to nahlásí jako skipped (local edits) a nechá ho beze změny. Pokud ho chcete přepsat, předejte --force (s rozsahem). Viz lingo push.

Po preservedKeys sáhněte tehdy, když má být ochrana trvalá a pro všechny jazyky; detekci místních úprav si nechte na jednorázové ruční zásahy.

Migrace ze staršího CLI#

Starší CLI umělo i přejmenování klíčů (zachování překladu při změně ID klíče). To už do současného CLI nepatří — stav překladu se sleduje podle hashe souboru, takže přejmenování klíče ho při dalším push přeloží znovu. Uzamknout, zachovat i ignorovat zůstávají, ale s jednou změnou: cesty používají tečkovou/závorkovou notaci (meta.version) místo dřívější lomítkové notace (meta/version).