Částečně lokalizované API — jedno sdílené pole přepíše překlad
import { Aside } from ‘@astrojs/starlight/components’;
Symptom
Sekce “Symptom”Na webu v původním jazyce se u jedné položky začne zobrazovat obsah v cizím jazyce. Konkrétně: hlavní jazyková verze katalogu měla správný nadpis, popis i meta tagy, ale blok otázek a odpovědí (FAQ) byl celý v jiném jazyce — v tom, do kterého se před několika hodinami zapisoval překlad.
Nic nehlásilo chybu. Zápis překladu proběhl s success, read-back v cílovém jazyce odpovídal, původní jazyk nikdo znovu nekontroloval.
Root cause
Sekce “Root cause”API přijímá u položky parametr jazyka a tvářilo se, že celou entitu ukládá per mutaci. Test na jedné kategorii to zdánlivě potvrdil — zapsal se překlad, původní jazyk zůstal nedotčený.
Jenže test porovnával jen ta pole, která se ověřovala vizuálně na stránce. Ve skutečnosti byla lokalizace zavedená po polích, a jedno z nich ji nemělo:
PATCH /api/category/111{"datalist": [{ "lang": "de", "seoTitle": "…", ← uloží se do německé mutace "description": "…", ← uloží se do německé mutace "descriptionSecond": "…", ← uloží se do německé mutace "seoDescription": "…", ← uloží se do německé mutace "faq": [...] ← ⚠ SPOLEČNÉ POLE, přepíše všechny jazyky}]}Čtení to potvrdilo jednoznačně:
GET /api/category/?id=111 → seoTitle: česky, faq: NĚMECKYGET /api/category/?id=111&lang=de → seoTitle: německy, faq: NĚMECKYTypicky jde o pole, které se do datového modelu přidalo později než lokalizační vrstva — strukturovaná data, JSON blob, pole příloh. Nikdo u něj nedoplnil jazykový rozměr a nikdo si toho nevšiml, protože dokud existuje jen jeden jazyk, chová se správně.
Zrádné na tom je, že chyba roste s každým dalším jazykem. Při plánovaných osmi mutacích by každá další přepsala FAQ té předchozí a výsledkem by bylo osm jazykových verzí sdílejících jeden náhodný jazyk — ten, který se zapisoval jako poslední.
Fix
Sekce “Fix”Krátkodobě: pole z payloadu úplně vypustit a překlady psát jen v polích, která lokalizaci skutečně mají.
payload = { "lang": lang, "seoTitle": title, "description": desc, "descriptionSecond": desc2, "seoDescription": meta, "faq": faq_items,}assert "faq" not in payload, "sdílené pole — smazalo by jiné jazyky"Vypustit, ne poslat prázdné — prázdná hodnota pole přepíše stejně jako plná.
Pak dohledat rozsah už vzniklé škody. Jednorázový sken nad všemi položkami, který hledá obsah bez znaků typických pro původní jazyk:
CIZI = re.compile(r'\b(welcher|which|quale|quel|cual)\b', re.I)for r in vsechny_polozky: for q in r['faq']: bez_diakritiky = len(re.findall(r'[ěščřžýáíéůú]', q['question'])) == 0 if bez_diakritiky and CIZI.search(q['question']): print('zasaženo:', r['id'], r['name'])V tomhle případě byla škoda omezená na jedinou položku (psal se jen testovací překlad), takže stačilo obsah napsat znovu. Kdyby proběhla celá vlna, byl by to nevratný přepis stovek položek bez zálohy.
Dlouhodobě to musí opravit dodavatel API — přidat poli jazykový rozměr jako mají ostatní.
Jak se tomu vyvarovat v jiných systémech
Sekce “Jak se tomu vyvarovat v jiných systémech”- Detection: před hromadným plněním udělej test na neaktivní položce pro každé pole zvlášť. Zapiš do cizího jazyka rozpoznatelnou hodnotu (
XX-TEST-<pole>), pak přečti původní jazyk a zkontroluj VŠECHNA pole, ne jen to, co zrovna testuješ. Pole, které se objeví i v původním jazyce, je sdílené. - Anti-pattern: read-back, který porovnává jen cílový jazyk. Potvrdí ti, že se zápis povedl, a mlčí o tom, co jsi přitom rozbil jinde. Verifikace zápisu do mutace musí vždy číst obě jazykové verze.
- Anti-pattern 2: usoudit „API umí mutace” z testu jednoho nebo dvou polí. Lokalizace je skoro vždy zavedená inkrementálně a pole přidaná později (JSON struktury, přílohy, strukturovaná data pro vyhledávače) na ni zapomínají nejčastěji.
- Lepší přístup: udělej si zálohu původního jazyka dřív, než se do mutací pustíš. Jeden dump všech položek stojí pár minut a je to jediná pojistka proti tiché ztrátě — tady se původní znění nepodařilo obnovit ani z historie a muselo se psát znovu.
- Lepší přístup 2: v payloadu měj explicitní whitelist polí, o kterých máš ověřeno, že jsou lokalizovaná, a tvrdou kontrolu (
assert), že se tam nic jiného nedostalo. Spolehnout se na to, že „to tam nikdo nepřidá”, nestačí — payload typicky skládá víc lidí nebo víc agentů.
Sister bugs / související
Sekce “Sister bugs / související”- Stejná třída problému jako i18n cookie přepíše jazyk tenanta — obojí vzniká tím, že jazykový rozměr není důsledně protažený celou cestou dat.
- Příbuzné je i prázdné pole truthy rozbíjí i18n fallback: tam fallback vybere špatnou jazykovou hodnotu, tady ji zápis rovnou přepíše.
- Často se vyskytuje společně s nejednotným tvarem odpovědi: detailní endpoint vrací obálku, výpis pole, a validátor, který zná jen jeden tvar, pak tiše hlásí prázdný obsah — a tím zamaskuje právě tenhle druh ztráty dat.