Sync jobs

The server-side engine behind CLI syncs — phases, strategies, statuses, resumability, and failure handling.

A sync job is a server-side, resumable job that reconciles a submitted set of translation strings against a namespace — diffing, pushing the changes, and optionally AI-translating whatever is still missing. It's the engine behind nrc langsync sync; you'll rarely create one by hand, but understanding how it behaves explains everything the CLI reports.

The four phases

Every job runs the same pipeline:

Planning. Compare the submitted marks and values against the namespace's current state, and write an ordered list of operations: create (mark doesn't exist), update (value changed), delete (only when pruning).
Pushing. Apply each operation. Progress counters (created / updated / deleted) tick as it goes.
Autotranslating. Run the batch AI engine over every term × language cell that's still empty, glossary included.
Finalizing. Assemble the resulting per-language state — the complete mark → value map for every attached language — which is what the CLI writes back to your local files.

Statuses

pending → planning → planned                        (terminal for dry-run)
                   └→ pushing → autotranslating → finalizing → completed

failed and cancelled are the other terminal states. A dry-run stops at planned with the plan attached — nothing is applied.

Poll the job over the API (GET /namespaces/{name}/sync/{jobId}) to watch it move; that's exactly what the CLI's live dashboard does. The response carries the status, per-phase progress counters, the plan (for dry-runs and in-flight pushes), the resulting per-language state, a count of cells that remained untranslated, and a list of per-operation failures if any occurred.

Options

Option	Default	What it does
`strategy`	`local`	`local` = push the submitted strings, then autotranslate. `server` = don't push anything; just autotranslate what's missing and return the server state. Use `server` for a read-only refresh.
`prune`	off	Delete server-side marks that are missing from the submitted set. Without it, marks you didn't submit are left alone.
`dryRun`	off	Stop after planning; return the plan without applying anything.
`waitForAutotranslate`	on	Whether the job should be polled through the autotranslate phase before the client reports completion.
`waitTimeoutSeconds`	120	Server-side cap on that wait.
`retranslateOnSourceChange`	off	When an update changes a term's source-language value, clear its other-language translations so the AI regenerates them from the new source. Off means stale translations stay until you deal with them.
source language	namespace default	The submitted strings' language. When it differs from the namespace default, autotranslate uses your language as the translation source — see source-of-truth language.

Reliability guarantees

Sync jobs are built to survive crashes and never double-charge AI work:

One worker at a time. Workers claim jobs with a short exclusive lease that they keep refreshing; a competing worker can't pick up a live job.
Resumable, idempotent operations. Every planned operation records whether it has been applied. If a worker dies mid-push, the next one resumes from the first unapplied operation; re-running an applied operation is a no-op.
Autotranslate fires at most once. The job records the moment autotranslate is triggered before dispatching it; resumption sees the marker and never re-triggers the AI batch.
Failures are captured, not fatal. If individual operations fail, the job continues, completes, and reports the failures list — three bad rows out of a hundred don't waste the other ninety-seven. The CLI surfaces these in its Issues block along with diagnostic hints (a common one: source values that are empty, which autotranslate skips).

Retention

Job records — the plan, progress counters, results, and failures — are kept for 7 days after completion, then deleted automatically. Pull anything you need for audits before that; the job's creation, completion, or failure is also permanently recorded in the audit log (sync_job.created / sync_job.completed / sync_job.failed).

Edge cases worth knowing

Pruning deletes are permanent. A local + prune job removes server marks missing from your submission — terms and all their translations. Run --dry-run first when in doubt.
server strategy never writes your submitted values. It's safe to run against a namespace someone else is editing — you'll get their edits, they won't get yours.
The wait is client-side convenience, not job control. If the wait times out, the job keeps running server-side; the CLI writes whatever is finished and tells you translations are still draining. Re-run nrc langsync pull later to pick up the rest.

CLI project sync — the tool that creates these jobs and everything about its flags.
Auto-translate — how the AI phase translates and what it costs.