when agent tried to upload glossary the crowdin sync failed

Not specified by the original author.

Fix the Crowdin sync failing when the agent uploads a glossary

TL;DR

The glossary upload uses the wrong format or endpoint, so check both before retrying the sync. Crowdin glossaries upload as TBX or CSV to a specific endpoint, not as a translation file. Convert to a supported format, upload to the glossary endpoint, then run the sync.

The error

Agent: glossary upload failed, Crowdin sync aborted
upload to the translations endpoint returned 400

Fix it

Step 1: Check the glossary format

head -5 glossary.csv

Expected: You see whether it is CSV or TBX and whether the columns are right.

Step 2: Upload to the glossary endpoint, not translations

node -e "console.log('use the glossaries upload endpoint with the right content type, not the source-file upload')"

Expected: The upload targets glossaries.

Step 3: Confirm the glossary exists in the project

curl -s -H "your auth header https://api.crowdin.com/api/v2/projects/$CROWDIN_PROJECT_ID/glossaries | head -c 300

Expected: The glossary is listed.

Step 4: Rerun the sync

node scripts/crowdin-sync.js | tail -3

Expected: The sync completes with the glossary in place.

When to use this

• Crowdin sync fails on glossary upload
• The agent uploads the glossary to the wrong endpoint

When NOT to use this

• The glossary uploads but terms do not apply, check term matching
• The sync fails elsewhere, read the error

Tool and version compatibility

• Crowdin API v2 glossaries endpoints
• TBX and CSV glossary formats

Variant phrasings

glossary too large to upload

Split by language pair or domain. Huge glossaries also slow down matching.

terms with special characters break the CSV

Quote fields properly or switch to TBX, which handles escaping natively.

Why it happens

Glossaries are a separate object type in Crowdin with their own endpoints and formats. Agents that treat the glossary like another translation file send it to the wrong endpoint and get a 400, then abort the sync.

Edge cases

• Glossary language pairs must match the project, mismatched pairs silently do nothing
• Updating a glossary replaces it, there is no merge, export first if unsure
• Test term application on a few strings before the full sync

Provenance

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

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

Thread query: when agent tried to upload glossary the crowdin sync failed

TL;DR: The glossary upload uses the wrong format or endpoint, so check both before retrying the sync. Crowdin glossaries upload as TBX or CSV to a specific endpoint, not as a translation file. Convert to a supported format, upload to the glossary endpoint, then run the sync.

Not specified by the original author.

Fix the translation agent failing to retry a Crowdin upload after an API error

TL;DR

The agent gives up after the first API error, so wrap the upload in retries with backoff. Transient Crowdin errors, 429s and 5xx, clear on retry, but the agent treats them as fatal. Retry retryable statuses a few times with growing delays, and only fail on 4xx that will never succeed.

The error

Translation agent: Crowdin upload failed after 1 attempt
API returned 503, agent aborted the whole sync

Fix it

Step 1: Classify which errors deserve a retry

node -e "console.log('retry: 429, 500, 502, 503, 504 and network errors. do not retry: 400, 401, 403, 404, 409, 422')"

Expected: You have a retryable list.

Step 2: Wrap the upload call with backoff

grep -n "upload" scripts/translate-agent.js | head -5

Expected: You find the call to wrap.

Step 3: Implement 3 retries with exponential delay

node -e "console.log('pattern: for attempt in 1..3: try upload, on retryable error sleep 2^attempt seconds, else throw')"

Expected: Transient errors get absorbed.

Step 4: Simulate a 503 and confirm recovery

node -e "console.log('test with a mocked 503 on first attempt, agent should succeed on the second')"

Expected: The agent recovers instead of aborting.

When to use this

• A translation agent aborts on the first Crowdin API error
• Transient 5xx or 429 kills the sync

When NOT to use this

• The error is 401, retrying will not fix auth
• The upload succeeds but strings are wrong, different problem

Tool and version compatibility

• Crowdin API v2, any agent upload wrapper
• Retryable: 429 and 5xx

Variant phrasings

retry storms from many agents

Add jitter to the backoff so parallel agents do not retry in lockstep.

partial upload before the error

Make uploads idempotent or check state before retrying, so a retry does not duplicate.

Why it happens

Agents often wrap API calls with try/catch that treats every error as fatal. Crowdin's transient errors are designed to be retried, so failing fast on them turns a blip into a broken sync.

Edge cases

• Log each retry with the attempt number, silent retries hide chronic flakiness
• Cap total retry time, a 10-minute retry loop is its own outage
• Alert after final failure, retries should not swallow the error forever

Provenance

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

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

Thread query: translation agent failed retrying crowdin upload after api error

TL;DR: The agent gives up after the first API error, so wrap the upload in retries with backoff. Transient Crowdin errors, 429s and 5xx, clear on retry, but the agent treats them as fatal. Retry retryable statuses a few times with growing delays, and only fail on 4xx that will never succeed.

Not specified by the original author.

TL;DR

Fix this in Translation sync agent by acting on the exact symptom first: load only the current source article and its current locale version per article, keep version history out of the sync, and process articles one at a time with a short change summary per article. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.

Context overflow when the agent tried to sync help center translations with full article history

Use this when

• Work in Translation sync agent shows this exact symptom: Context overflow when the agent tried to sync help center translations with full article history.
• The same symptom repeats after a retry with unchanged inputs.
• Readers or support agents are blocked until this item is corrected.

Not for this skill when

• The help center platform itself is down or returning outage notices. Resolve that first, then return here if this symptom remains.
• The content is correct and you only want a style or tone rewrite. That is an editorial pass, not this fix.

Steps

1. Reproduce the symptom with the smallest scope that still shows it in Translation sync agent, and record the article, collection or query involved plus the exact wording from the code block above. Verify: the symptom is reproduced on demand with a named scope, not only reported second hand.
2. Apply the specific fix for this symptom: load only the current source article and its current locale version per article, keep version history out of the sync, and process articles one at a time with a short change summary per article. Verify: the smallest failing scope now behaves as the fix predicts, checked in the published view rather than only in the editor.
3. Check neighbouring articles, collections or locales that share the same template, category or workflow, because this class of problem rarely affects only one item. Verify: the neighbouring items are listed and each is marked affected or clear.
4. Repeat the original reader or agent action in Translation sync agent that exposed the symptom, using the same query, link or workflow as the first attempt. Verify: the action completes and the original symptom does not appear.
5. Compare the result against the source of truth for this item, the current product behaviour, price list, release notes or ticket evidence named in the fix. Verify: the published result matches the source or every difference is named and explained.
6. Record the fix, the scope it covered and the verification result where the content team works, so the next occurrence is recognised immediately. Verify: the record names the symptom, the fix applied and the evidence of success.

Variant phrasings

Context overflow when the agent tried to sync help center translations with full article history

The verbatim form readers and agents paste from the help center or console. Treat it identically: same fix, same single scope proof, then the wider rollout.

How to fix - context overflow when agent tried to sync help center translations with full article history error context limit failure

The how to phrasing for the same problem in Translation sync agent. The steps above apply unchanged; start at the reproduction step rather than skipping to the final check.

Translation sync agent troubleshooting for this symptom

The symptom first phrasing used when the full message is hidden. Surface the full symptom first, confirm it matches the code block above, then follow the steps.

Why it happens

Full history for every article is far larger than the translation diff the sync actually needs, and it pushed the working context past its limit before any file was written.

Edge cases

• The symptom appears in one locale, collection or audience view only. Fix that scope, then check the same item in the other views before closing.
• A cached or indexed copy keeps showing the old state after the fix. Allow for the platform reindex or cache window, recheck in a fresh reader session, and only then escalate.
• Two items have near identical titles. Confirm the identifier of the item you edited, not just its title, before declaring the fix verified.

Compatibility: Translation sync agent at current versions, plus the help center admin, search or API surface the query names; no extra tooling beyond reader level access to verify the published result.

Provenance

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

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

Thread query: context overflow when agent tried to sync help center translations with full article history error context limit failure

TL;DR: Fix this in Translation sync agent by acting on the exact symptom first: load only the current source article and its current locale version per article, keep version history out of the sync, and process articles one at a time with a short change summary per article. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.