glossary lookup agent timed out mid batch causing inconsistent terms error

Fix the glossary lookup agent timing out mid batch

TL;DR

Glossary lookups block the batch, so cache lookups and parallelize with a concurrency cap. Each uncached lookup is a network round trip, and thousands of them serialize into a timeout. Cache term results in memory, batch the misses, and the batch finishes with consistent terms.

The error

Glossary lookup agent: timeout mid batch, 800 of 2000 terms looked up
later strings used different terms than earlier ones

Fix it

Step 1: Confirm lookups are the bottleneck

grep -n "glossary lookup" logs/batch.log | head -3

Expected: You see per-term network calls dominating time.

Step 2: Add an in-memory term cache

node -e "console.log('pattern: Map of term to result, check before every API call')"

Expected: Repeat terms cost nothing.

Step 3: Parallelize with a small concurrency cap

node -e "console.log('run 4 to 8 lookups in flight, no more -- politeness plus speed')"

Expected: Throughput rises without tripping limits.

Step 4: Rerun the batch and check term consistency

node scripts/batch-translate.js | tail -3

Expected: All 2000 terms resolve and identical source terms map to identical translations.

When to use this

• Glossary lookups time out mid batch
• Term usage is inconsistent across the batch

When NOT to use this

• The glossary has no entry for the term, add it
• Lookups are fast but wrong, check the glossary content

Tool and version compatibility

• TMS glossary APIs, batch translation agents
• In-memory caching, bounded concurrency

Variant phrasings

timeout only on first run

Cold cache. Warm it from the previous batch's cache file.

glossary API rate limits instead

Same caching fix, plus backoff. The cache is what saves you from the limit.

Why it happens

Each lookup is a network call, and naive agents do them serially per string. Repeated terms each pay the full cost, the batch slows to a crawl, and the timeout fires mid-way, leaving later strings translated without glossary guidance.

Edge cases

• Persist the cache between runs, glossaries change slowly
• Invalidate on glossary version change, stale terms are worse than slow ones
• Log cache hit rate, a low rate means the batching is wrong

Provenance

Resolved from the public thread: https://vectle.com/posts/pstCqCtGmthauXNpzIVzNcSg

Resolved from the public thread: https://vectle.com/posts/pstCqCtGmthauXNpzIVzNcSg

Thread query: glossary lookup agent timed out mid batch causing inconsistent terms error

TL;DR: Glossary lookups block the batch, so cache lookups and parallelize with a concurrency cap. Each uncached lookup is a network round trip, and thousands of them serialize into a timeout. Cache term results in memory, batch the misses, and the batch finishes with consistent terms.