Localize

Máte řetězec nebo malý objekt s řetězci, který potřebujete hned teď v jiném jazyce – popisek formuláře, notifikace, krátký blok UI textu, na který uživatel čeká. Nechcete kvůli jednomu překladu rozjíždět webhook endpoint ani dotazovat job. Chcete text odeslat a rovnou dostat překlad zpět.

Právě k tomu slouží synchronní endpoint Localize: jeden požadavek, zpátky přeložená data ve stejné struktuře. Pošlete obsah klíč–hodnota metodou POST se zdrojovým a cílovým jazykem, volání po dobu překladu blokuje a odpověď vrátí stejný objekt s přeloženými hodnotami a nezměněnou strukturou. Není tu žádný job ke sledování ani druhé volání navíc.

Nejde o žádné generické volání modelu. Všechno běží přes lokalizační engine, který jste nastavili – jeho glosář, hlas značky, instrukce a výběr modelu pro jednotlivé jazyky – tedy stejný engine, který používá i async API. Rozdíl je jen ve formě: async rozprostře jeden požadavek do více jazyků a výsledky vrací průběžně, zatímco toto volání zpracuje jeden jazykový pár a vrátí ho inline.

Na této stránce

• Požadavek
• Odpověď
• Příklady
• Co se děje při lokalizaci
• Další kroky

Požadavek#

POST /process/localize

Ověřte se pomocí hlavičky X-API-Key. Klíče jsou vázané na organizaci a mají přístup ke každému engine ve vaší organizaci – kde je vygenerovat, najdete v části Authentication, a úplný model chyb v části Errors and status codes.

{
  "engineId": "eng_abc123",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hello, world!",
    "cta": "Get started"
  },
  "hints": {
    "cta": ["Landing page", "Primary button"]
  }
}

Odpověď#

Odpověď vrací přeložený obsah ve stejné struktuře, jakou jste poslali, plus model, který ho vytvořil, a cenu za daný požadavek. Vrátí se stejné klíče, ve stejném vnoření – váš kód si tak může překlad vyčíst ze struktury, kterou už zná.

Objekt usage rozepisuje cenu volání po položkách, takže můžete náklady přiřadit bez samostatného dotazu do billing systému:

{
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "greeting": "Hallo, Welt!",
    "cta": "Jetzt starten"
  },
  "model": "anthropic/claude-sonnet-4.5",
  "usage": {
    "inputTokens": 2789,
    "outputTokens": 861,
    "cacheReadTokens": 0,
    "cacheWriteTokens": 0,
    "llmCost": 0.02129,
    "localizationCost": 0.001722,
    "cost": 0.023012
  }
}

Příklady#

Stejné volání v pěti jazycích. Kvůli přehlednosti každý příklad posílá plochý objekt; data ale přijímá i vnořené objekty a pole a odpověď se vrátí v přesně té struktuře, kterou odešlete.

const response = await fetch(
  "https://api.lingo.dev/process/localize",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      engineId: "eng_abc123",
      sourceLocale: "en",
      targetLocale: "de",
      data: {
        greeting: "Hello, world!",
        cta: "Get started",
      },
    }),
  }
);

const { data } = await response.json();
// { greeting: "Hallo, Welt!", cta: "Jetzt starten" }

Co se děje při lokalizaci#

Jediný POST v sobě skrývá sérii kroků a stojí za to vědět, jakých – právě díky nim je výstup konzistentní se zbytkem vašeho lokalizovaného obsahu, místo aby šlo jen o jednorázový odhad modelu. Když požadavek dorazí na endpoint, engine postupně použije celou svou konfiguraci:

1. Výběr modelu – Vybere LLM model s nejvyšší prioritou, který odpovídá danému jazykovému páru. Modely specifické pro konkrétní jazyk mají přednost před wildcard modely (*). Pokud primární model selže, engine automaticky přejde na další model v pořadí.

2. Hlas značky – Načte hlas značky pro cílový jazyk, a pokud pro něj neexistuje specifická varianta, použije wildcard hlas značky.

3. Instrukce – Načte všechny instrukce odpovídající cílovému jazyku, včetně wildcard instrukcí.

4. Vyhledání v glosáři – Rozdělí vstupní hodnoty na prohledávatelné chunky, vygeneruje embeddingy a provede vyhledávání podle vektorové podobnosti v glosáři engine. Nalezené termíny vynutí přesné překlady nebo je označí jako nepřeložitelné, takže projdou beze změny.

5. Generování – Odešle sestavený prompt vybranému modelu a potom zparsuje a ověří JSON odpověď.

Jde o stejnou pipeline kroků engine, kterou async API spouští pro každý job. Když místo async použijete sync, mění se způsob doručení, ne to, jak se překlad vytváří – takže řetězec přeložený tady i tentýž řetězec přeložený v async jobu skončí na stejných termínech v glosáři a se stejným hlasem.

Další kroky#