move_translation_key
Move a translation key to another layer, to another key path, or both, carrying every locale that defines it. Pass toLayer to promote an app-layer key to a shared layer once a second app needs it (or to demote a shared key that turned out to be app-specific); call discover first, layerGraph.shared names the layers more than one app consumes. Pass newKey alone to rename the key in place across every locale file of its layer. Writes nothing at all if the destination already holds the key with a different value in any locale; if it holds the same value, that locale is deduplicated instead. Use dryRun to preview the plan.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
layer | string | yes | Layer the key lives in today, from discover. Example: "app-admin". |
key | string | yes | Dot-separated key path to move. Example: "calendar.views.save". |
toLayer | string | no | Layer to move it to, from discover. Example: "root". Omit (or repeat layer) to rename the key within its current layer, which then requires newKey. |
newKey | string | no | Key path to give it. Example: "common.actions.save". Omit to keep the current path, which then requires toLayer. |
dryRun | boolean | no | Return the plan without writing any files. Default: false. |
projectDir | string | no | Absolute path to the project root. Defaults to I18N_PROJECT_DIR, then server cwd. Example: "/home/user/my-app". |
Result
| Field | Type | Description |
|---|---|---|
dryRun | boolean | True when nothing was written because a plan was asked for. Absent otherwise. |
wouldMove | object[] | The plan, one entry per locale. Present only with dryRun. |
movedLocales | string[] | Locales whose value was written to the destination layer. Absent on a dry run. |
deduplicatedLocales | string[] | Locales where the destination already held this value, so only the source copy was dropped. |
filesWritten | integer | Number of locale files changed on disk. Absent on a dry run. |
fromLayer | string | Layer the key was moved out of. |
toLayer | string | Layer the key was moved into. |
key | string | The key as it was before the move. |
newKey | string | The key path it now has. Equal to key when only the layer changed. |
notFoundInLocales | string[] | Locales whose source layer does not define the key at all. |
conflictsInLocales | string[] | Locales where the destination holds a different value. Nothing is written at all when this is non-empty. |
summary | object | Counts of what the run did. |
message | string | The step to take next, as the surface the call ran on phrases it. Present only when there is no summary to carry it. |
wouldRename | object[] | The plan, one entry per locale. Present only with dryRun. |
renamed | string[] | Locales whose file was rewritten with the new key. Absent on a dry run. |
oldKey | string | The key path before the rename. |
skippedDueToConflict | string[] | Locales left untouched because of such a conflict. |
Behavior Hints
A host reads these to decide whether a call needs your confirmation first.
| Hint | Value |
|---|---|
readOnlyHint | false |
destructiveHint | true |
idempotentHint | false |
openWorldHint | false |
Paired CLI Command
The same operation runs from a terminal as the-i18n-cli move, whose page documents its flags.