Skip to content

Update a key's source value

Seeding a key with create_key or create_keys_bulk sets its source value once. Re-running with a changed source_value does nothing, by design, so an automated seed never clobbers source text. Here is how to deliberately change a key's source after it already exists.

The no-op you'll hit

create_key and create_keys_bulk accept a source_value, but only honour it when they actually create the key. Call them again on a key that already exists and the new source_value is silently dropped: the call still succeeds, the key comes back with created: false, and the source text is unchanged.

// create_keys_bulk: source_value on a key that ALREADY exists
{ "items": [
  { "namespace": "common", "name": "checkout.title",
    "source_value": "Checkout" }
] }

// → no update_source: the existing source is left untouched
{ "results": [{ "index": 0, "status": "ok", "created": false }] }

Fix: update_source

Add update_source: true to the key: it's a per-key field (on create_key, or on each items[] entry of create_keys_bulk), never a global flag. The source is then upserted even on an existing key (created stays false). It's opt-in, so a routine re-seed never changes source text by accident.

// update_source is a PER-ITEM flag, never a global one
{ "items": [
  { "namespace": "common", "name": "checkout.title",
    "source_value": "Checkout", "update_source": true }
] }

// → created:false (the key existed) but the source is now upserted
{ "results": [{ "index": 0, "status": "ok", "created": false }] }

Both run on the MCP surface (an mcp:*-scoped key), and the project must already have a source language. The change is version-bumped and recorded in the key's history.

Or re-import the source language

The one-shot i18next import also upserts source values. Re-importing your source-language files updates every existing source in a single call: convenient when the source text already lives in your repo.

# or re-import your source-language files: import upserts source values
sonenta import "./locales/en/**/*.json"   # en = your source language

Next

Migrate from i18next: Bring an existing catalogue into Sonenta in one command.
CLI: Import, push, pull and publish from your terminal.
Key nesting: Flat vs nested keys, and the dotted-key trap.