---
name: localization-reuse-map
description: >-
  Produce a per-screen localization-reuse map for one redesigned screen (iOS / Android / web): for each UI
  element it pairs the NEW localization key + values with the LEGACY key + values per platform and the
  content team's ACTUAL CMS copy read live from Figma Dev Mode annotations, recommends a reuse verdict
  (reuse / review / new) the content team confirms, renders a key-to-UI overlay plus a per-key red-box
  screenpiece, and publishes a Confluence page live (idempotent). Also scans the implemented screen for
  error and dynamic keys the registry misses. Use when mapping a redesigned screen's strings to the
  legacy ones for reuse, one screen at a time. Trigger phrases  -  "localization reuse map", "map old keys
  to new keys for this screen", "which legacy translations can we reuse", "reuse existing translations",
  "CMS copy from Figma annotations", "localization excel", "CMS import sheet", "/localization-reuse-map".
---

# Localization Reuse Map  -  old↔new localization map for one screen

Produces, for **one redesigned screen**, the table content management needs: every UI element with its
**new** key + translations, its **legacy** key + translations per platform, and the content team's **actual
CMS copy** (Figma annotations), plus a **recommended** reuse verdict, a **visual key↔UI overlay**, and a
**per-key screenpiece** (a red-box crop showing where that key lives on screen) embedded in each table row  -  
published **live** as a Confluence page. The skill **recommends; the content team decides**.

**Detail:** [reference/sources-and-recipes.md](reference/sources-and-recipes.md) (data model + exact
per-source retrieval recipes, incl. CMS annotations + the implemented-screen scan) ·
[reference/format-and-output.md](reference/format-and-output.md) (verdict taxonomy + mapping JSON schema +
CMS columns + Confluence output) · [reference/publish-and-snapshot.md](reference/publish-and-snapshot.md)
(publish live to Confluence + the `localizations/` PR + snapshot the resources in-repo).
**Input shape:** [example-mapping.json](example-mapping.json).

## Project configuration  -  resolve these first
Nothing about any one company is baked in. Establish these once per project (ask the user, or read them from
the project's own docs) and reuse them for every screen:

| What | Used for | Example |
|---|---|---|
| Specs repo + design-export path | screen frames, `components-used.md`, `screenshot.png`, `tree.json` | `design-export/<project>/screens/<slug>/` |
| Resources root | authored/suggested new values + the component registry | `resources/Localization/Suggested/<Key>.json` |
| Legacy label endpoint + headers | refreshing the legacy value snapshot | `--endpoint` + `--headers-file` |
| Legacy key prefix (if any) | display-only re-prefixing in the table | mapping `legacyKeyPrefix` |
| Web i18n convention (legacy AND new, if either is a web app) | which call form + key-file shape the tracer/scanner look for | `t('key')` / `$t('key')` reading `locales/<lang>.json` |
| Confluence base URL / space / parent | publishing | `CONFLUENCE_BASE_URL` / `_SPACE` / `_PARENT` |
| CMS bucket taxonomy | the spreadsheet's Property Group / Module | `--taxonomy cms-taxonomy.json` |
| Document language | template chrome + author-written fields | `--ui-lang en` (default) / `tr` |

Secrets stay in a keychain item or a `--headers-file`, never in the mapping, the docs, or argv.

## Scope
One screen per run, every platform the screen exists on; publishes the map **live to Confluence** (idempotent
update-in-place) and optionally to the specs repo's `localizations/` as a PR  -  the user is asked which target
+ space/formats. Out: cross-screen rollups and minting/defining new keys (that is the resource-authoring flow,
not this skill).

## Invariants  -  read before running
- **One screen per run.** The unit is a screen; keys owned by a *reusable component* are flagged, not
  re-mapped  -  they are mapped once where that component is mapped.
- **The skill recommends; the content team decides** the reuse call. Never present a verdict as final.
- **Never invent a legacy value.** Legacy translations are backend-served  -  fetch them or leave the Old
  column blank with a note. Blank beats a guess. (See sources-and-recipes "Legacy translation values".)
- **Never invent a CMS value.** The CMS column is the content team's *actual* copy  -  fetch it from the Figma
  annotation or leave it blank. The annotation is authoritative as their final copy; it is shown
  **additively** (it never overwrites the `new` value), and a CMS≠new difference is surfaced (⚠), not hidden.
- **Figma is live-first.** The CMS annotations + overlay are fetched from the Figma **REST API** (or MCP),
  falling back to the in-repo design export only when neither is reachable  -  because Figma is edited
  continuously and the snapshot can be stale.
- **Read-only across every source.** This skill produces an artifact; it edits no repo and defines no key.
  (The only writes are the Confluence page it publishes and the optional `localizations/` PR.)
- **Author the document in the content team's language.** The author-supplied `element` labels and `note`
  annotations must match the chrome language (`--ui-lang`)  -  they are the only free text in the doc, so a
  mixed-language run reads as half-translated. Only keys and translation values stay verbatim.

## Sources (self-contained  -  no other skill required)
Retrieval is a **cross-reference, not a skim**  -  that distinction is the whole skill. Full recipes:
[reference/sources-and-recipes.md](reference/sources-and-recipes.md).
- **New keys**  -  cross-reference three: the design export's `screens/<frame>/components-used.md` (which
  components, **all** state frames) **×** each component's registry `<node>.json → localizationKeys` (keys it
  renders internally, often absent from screen code) **×** the screen's code (what it wires). Union; tag
  screen-specific / component-owned / shared.
- **New values**  -  the authored per-key source (`Suggested/<Key>.json`, 8 langs):
  `scripts/resolve-new-values.py --langs all --catalog <shipped catalog>`. **Always pass
  `--catalog`.** The Suggested tree is a generated snapshot and goes stale the moment a key is
  added upstream, so a missing file means "not in this snapshot", never "this key is
  unauthored". With the catalog the script resolves the value anyway and reports that the
  snapshot needs `snapshot-resources.sh`; without it every stale key reads as needing authoring.
- **CMS values (content team's actual copy)**  -  Figma Dev Mode annotations, fetched **live**:
  `scripts/fetch-annotations.py --mapping <map>.json` (REST primary → `--from-mcp` → `--local` fallback).
  Map each annotation to its row by `nodeId` → fill `cms:{tr,en}`. Blank when not yet annotated.
- **Error / dynamic keys the cross-reference misses**  -  scan the *implemented* screen:
  `scripts/scan-screen-keys.py --screen-path <dir>` → error/validation/alert + dynamic/`String(format:)`/
  variable-`.localized` keys (categorized). Fold the `error`/`dynamic` hits into the mapping.
- **Legacy keys**  -  **trace the screen**, don't skim: iOS VC→VM→**cell presentation models**
  (`"Key".localized`); Android layout `@string/Key`; web component→ `t('key')`/`$t('key')` call site,
  key resolved against the legacy app's `locales/<lang>.json` (or equivalent i18n catalog). The screen's
  spec names the legacy entry class/component.
- **Legacy values**  -  the in-repo label snapshot (offline, no network per run):
  `scripts/resolve-legacy-values.py --snapshot-root <resources>/Localization/Legacy --keys "..." --langs all`.
  Refresh the snapshot (the only network step) with `scripts/fetch-legacy-labels.py --endpoint ...
  --headers-file ...`. `--live` to verify; `--plist-root` last-resort.
- **A legacy key prefix** the backend stores but the app strips is kept out of the mapping and re-added for
  display via the mapping's `legacyKeyPrefix` (`Continue` → displayed `Mobile-Continue`).
- **Screenshot**  -  the design export's `screens/<frame>/screenshot.png`.
- **Overlay (key↔UI image)**  -  `scripts/render-overlay.py --mapping <map>.json` (REST primary → `--spec`
  MCP). Embedded in the page as a "key map" section; needs headless Chrome (falls back to `.html`).
- **Per-key screenpieces (keyshots)**  -  `scripts/render-key-shots.py --mapping <map>.json` (same REST /
  `--spec` modes and the same row↔node matcher as the overlay): one red-box crop per matched row →
  `keyshots/keyshot__<NN>__<key>.png` + `<slug>.keyshots.manifest.json`; the table's "Screenshot"
  cells embed them. Unmatched rows render "  -  ", never a guessed crop.
- **Document language**  -  `--ui-lang en` (default) or `tr`.

*Figma: for **structure** (components, nodes, screenshot) the in-repo design export is the source. For **CMS
annotations + the overlay** the live **REST API** is primary (token in keychain `FIGMA_ACCESS_TOKEN`) with
**MCP** (Dev Mode) as the no-rate-limit alternative; the export is the offline fallback.*

## Decision rules
- Verdict per row: **reuse** (same function + same/equivalent value, or a clean shared key on both legacy
  platforms) · **review** (same function but value / key / cross-platform drift) · **new** (no legacy
  counterpart). Full table in format-and-output.md.
- Key owned by a reusable component, not the screen → flag it (`(owned by ...)`), don't double-map.
- Legacy keys differ across the platforms present (iOS/Android/web) → keep every column that has one,
  default to **review** (drift to resolve).
- A `tr` value equal to its `en` value → note it (untranslated) regardless of verdict.
- **CMS value present and ≠ the `new` value** → the renderer marks it ⚠; call it out in the note (the content
  team's final copy diverged from the mock). CMS is additive context for the verdict, not a verdict input.
- **Dynamic key** that can't be statically resolved → map it with `verdict: review` + a "dynamic  -  enumerate
  at runtime" note; never drop it.

## Procedure

*Ask the user up front for what's missing* (interactive): the implemented **screen path**, the **Figma
file key + node-ids** (or confirm the design-export slug), and at publish time the **Confluence target**
(space / parent / formats). Don't block on what you can derive; ask only for gaps.

1. **Enumerate new keys + elements (cross-reference).** From the design export get the screen's components
   (all state frames) + screenshot; read each component's registry `localizationKeys`; read the screen's
   code for wired keys. Union → one element per key, tagged screen/component/shared.
2. **Scan the implemented screen for the keys the cross-reference misses** (script):
   `python3 scripts/scan-screen-keys.py --screen-path <dir>` → fold the **error** + **dynamic** hits into the
   element list (the static union is blind to them); diff `static` hits vs the registry union.
3. **Resolve new values** (script): `python3 scripts/resolve-new-values.py --resources-root <resources>
   --keys "<all keys>" --langs all --catalog <shipped catalog>`. Only a key absent from BOTH the
   snapshot and the catalog is genuinely unauthored; anything the catalog resolved means the
   snapshot is stale (refresh it, do not open authoring requests).
4. **Fetch CMS copy from Figma annotations** (script): `python3 scripts/fetch-annotations.py --mapping
   <map>.json` (REST primary → `--from-mcp` → `--local`). Map each annotation to its row by `nodeId`
   (store `cmsNodeId`) → fill `cms:{tr,en}`. Leave blank where unannotated; flag TR-without-EN.
5. **Trace legacy keys, every platform** (sources-and-recipes recipes): the spec's legacy reference →
   VM → cell presentation models (iOS); layout `@string/` (Android). Don't stop at the VM.
6. **Resolve legacy values** (script): `python3 scripts/resolve-legacy-values.py --snapshot-root
   <resources>/Localization/Legacy --keys "<legacy keys>" --langs all` (offline snapshot; refresh it with
   `fetch-legacy-labels.py` when needed). Absent → leave blank + note.
7. **Assemble the mapping JSON** (schema in format-and-output.md)  -  one row per element: new/legacy keys +
   8-lang `new`/`legacy` values + `cms`/`cmsNodeId` + a recommended `verdict` + `note`. Add `screenshot`,
   `figmaFileKey`, and `legacyKeyPrefix` when the backend uses one.
8. **Render the key↔UI overlay** (script): `python3 scripts/render-overlay.py --mapping <map>.json --out
   <dir>` → `<slug>.overlay.png`; set the mapping's top-level `overlay` to that filename. **The overlay does
   NOT need annotations**  -  with zero CMS annotations it still maps every keyed element to its spot on the
   screen (gray "awaiting copy" cards). **Card numbers = table row numbers:** each card (and its dot) is
   numbered by the matched row's position in `mapping.rows`, i.e. the same number `build-artifact` prints in
   the table  -  so a mark on the screen and its table row always agree (they are NOT renumbered by layout
   order). Pick the geometry source in this order:
   - **REST** (`--mapping` with `figmaFileKey` + the real **frame node**): full per-label geometry. Get the
     frame's true node-id from the design export screen's `tree.json` **root `nodeId`** (the folder-name
     suffix and any id in the old map are often stale/wrong  -  verify the node's text is actually this
     screen's). A frame may include background content (the screen shown as a sheet over another)  -  the
     non-matching nodes are dropped automatically.
   - **`--spec` (screenshot-anchored, no token / when REST geometry is noisy or unavailable)**  -  the reliable
     fallback the agent drives: read each visible element's box **off the clean screenshot**, set that row's
     `cmsNodeId` to a synthetic id (`n1`, `n2`, ...), and emit a spec page `{fileKey, pages:[{nodeId, image:
     "<screenshot dataURL>", frame:{w,h}, nodes:[{id:"n1", characters:"<on-screen text>", x,y,w,h, side}]}]}`.
     `render-overlay` anchors each card by `cmsNodeId` → exact key, positions from the real render.
   - **`side: "left" | "right"` per node (default left)**  -  put a card on the side of the frame its target sits
     on, so the connector stays short and doesn't cross the whole screen. Essential for **two-column layouts**:
     flag the right-column entries `"side":"right"` and they render as a right-hand card column with mirrored
     connectors; the left column stays left. Cards on each side are numbered and stacked independently.
   - The export's `tree.json` alone is **component-instance level** (no per-label geometry)  -  use it for the
     frame node-id, not for label boxes. No Chrome → `.html` fallback.

   **Mark component-owned keys on the overlay too.** A screen is mostly reusable-component instances
   (list rows, promotion grids, summary cards) whose keys the screen code never wires  -  but the content team
   still sees that copy on this screen. Map them here (this is where the component is used), each flagged
   `(owned by <Component>)` in its `note`, and anchor them on the screenshot. Pull the component's keys from
   its registry `<node>.json → localizationKeys`. These are the keys a plain screen-code scan is blind to.

   **One screen, several states → several screenshots, one composite overlay.** A key like an "Added" badge or
   a "Remove" link only appears in one state, not the default mock. Render one overlay per state (each
   `--spec` a different screenshot with that state's `cmsNodeId`s  -  `render-overlay` cards only the rows whose
   node matches that spec, so reusing a row's `cmsNodeId` across states is fine), then **vertically
   composite** the per-state overlays into one PNG (pad to max width, dark `#1e1e1e` gutter) and set that as
   the mapping's `overlay`  -  `build-artifact` embeds a single overlay, so the composite is how all states
   reach the doc. Keep the standalone per-state PNGs beside it.

   **Isolate one component variant when you want a clean render of it:** exported **library** node-ids go
   **stale** once the Figma file re-versions (`/components` may return 0, `/images` returns `null`). Don't
   chase them  -  the current screen **frame** node still renders, so walk its live node tree
   (`GET /files/<key>/nodes?ids=<frame>&depth=6`) for the `INSTANCE` whose `name` is the component, render
   **that** instance id, and take per-label boxes from its own text nodes' `absoluteBoundingBox` (× the render
   `scale`). No live token / render fails → just **crop the variant out of a state screenshot**; a crop of the
   real card is an equally valid variant image.

   **Interactive  -  guide the developer here:** if no annotations were found, say so and tell them you'll map
   keys to UI by reading the screen; confirm the **screen state** (which mock/screenshot) and that the
   anchored element list looks right before rendering.
9. **Render the per-key screenpieces (keyshots)** (script): `python3 scripts/render-key-shots.py --mapping
   <map>.json --out <dir> [--slug <slug>]` → `keyshots/keyshot__<NN>__<key>.png` (one red-box crop per
   matched row; **NN = the table row number**, same numbering as the overlay cards) +
   `<slug>.keyshots.manifest.json`. Reuses the overlay's geometry inputs verbatim: REST (visible text nodes
   only  -  ancestor-visibility + opacity filtered) or the same `--spec` file(s) you built for step 8
   (repeatable  -  one per screen state; `image` may be a file path, e.g. the committed `screenshot.png`).
   Set the mapping's top-level `keyshots` to the manifest filename; rows the geometry can't match land in
   the manifest's `missing` and their table cells render "  -  ". Detail in
   [reference/format-and-output.md](reference/format-and-output.md).
10. **Build the artifacts** (script): `python3 scripts/build-artifact.py <mapping>.json --out <dir>` →
    `<slug>.md` + `<slug>.confluence.xml` + `<slug>.preview.html` (CMS columns + the overlay key-map section
    + the per-key "Screenshot" table cells when `keyshots` is set).
    Add `--docx` / `--pdf` (or `--all`) for the content team  -  `.docx` is pure-stdlib/offline; `.pdf` uses an
    installed renderer (LibreOffice → Chrome → wkhtmltopdf), skipped with a note if none is present.
11. **Build the CMS import spreadsheet** (script): `python3 scripts/build-spreadsheet.py <mapping>.json --out
    <dir>` → `<slug>.localization.xlsx`  -  a **real Excel file** (an OOXML zip written with the Python **stdlib
    only**, no pip / no network, the same trick `build-artifact.py` uses for `.docx`; add `--csv` for a CSV
    alongside, `--csv-only` when Excel isn't wanted). One row per key in the content team's CMS-import columns:
    **Channel** · **Property Group** / **Property Module** (deduced from the key namespace  -  bucket names come
    from `--taxonomy`; a row overrides with `propertyGroup` / `propertyModule`) · **Key** (our `newKey`,
    component tag stripped) · **EN / TR / AR Value** (our authored `new` values) · **Anotation EN / TR** (the
    content team's CMS Figma annotations  -  `cms.en` / `cms.tr`). This file is attached to the Confluence page
    at publish (step 13). Format detail in [reference/format-and-output.md](reference/format-and-output.md).
12. **Fidelity check  -  GATE before publish** (script): `python3 scripts/verify-map.py --mapping <map>.json
    --screen-path <dir> [--resources-root <res>]`. Reconciles the map against the **real screen code**:
    **UNVERIFIED** keys (a `newKey` not wired anywhere) → fix or drop; **wired-but-unmapped** keys (a
    localization-key reference in code with no row) → add rows, it's a coverage gap; **value gaps** /
    **untranslated** (tr==en) → resolve or note. Exit code 2 = hard issues  -  don't publish until clean (or a
    waiver is conscious). This is what catches a stale/typo'd key or a missed downstream state before it ships.
13. **Publish** ([reference/publish-and-snapshot.md](reference/publish-and-snapshot.md))  -  ask the user which
    target(s): **(A) Confluence, live & idempotent**  -  `python3 scripts/publish-confluence.py --xml
    <slug>.confluence.xml --screen "<name>" --screenshot screenshot.png --overlay <slug>.overlay.png
    --keyshots <slug>.keyshots.manifest.json --attach <slug>.localization.xlsx` (Server/DC Bearer from the
    keychain; base URL / space / parent from flags or `CONFLUENCE_*` env; updates the screen's page **in
    place** on re-run). The `--attach` file rides along as a page attachment and, being a spreadsheet, also
    gets a `view-file` macro so it **renders inline**. **(B) specs-repo PR**  -  copy the canonical set (incl.
    `<slug>.localization.xlsx`, the manifest and `keyshots/`) into `localizations/<slug>/` and open an
    additive PR.

*(Pipeline  -  runs **after** the screen spec: dev generates spec → generates this map → publishes. Resources
are read from the in-repo snapshot when present; refresh it with `scripts/snapshot-resources.sh`.)*

## Verification
- **Run `verify-map.py` (the fidelity gate)**  -  it reconciles the map against the real screen code and is
  the scripted form of "counts must reconcile": every `newKey` is wired (or component/dynamic-exempt), no
  localization-key reference in code is left unmapped, no fabricated/empty values. Fix what it flags before
  publishing. `scan-screen-keys.py` error/dynamic hits must be accounted for as rows.
- Every row has a `verdict`; no Old **or CMS** value is fabricated (blank or sourced only).
- `build-artifact.py` runs clean; the `.md` carries the header + legend + totals + the fixed column order
  including the CMS columns.
- The overlay PNG was produced (or a `.html` fallback noted) and is referenced by the mapping's `overlay`.
- **The keyshots were rendered**  -  `render-key-shots.py` wrote one PNG per matched row, the mapping's
  `keyshots` names the manifest, every non-"  -  " Screenshot cell resolves to a file that exists, and nothing in
  `keyshots/` is orphaned. Renaming a key or reordering rows renumbers `NN`: **re-render, never hand-rename.**
- **The CMS spreadsheet was built**  -  `build-spreadsheet.py` wrote `<slug>.localization.xlsx` with one row per
  key (row count = `mapping.rows`), the fixed 9 columns, and it is `--attach`ed at publish. Values come from
  `new`, annotations from `cms`  -  never fabricated (blank where unsourced, same rule as the doc).
- Publishing is **idempotent**: a second `publish-confluence.py` run on the same screen reports `updated`
  (version-bump) of the **same** page id  -  never a duplicate.

## Pitfalls
- A large specs repo's recursive Git tree truncates (~43k paths)  -  use `gh search code`, not the tree API.
- New key namespace ≠ legacy flat key (`SignUpAccountDetails.ContinueButton` vs `Continue`)  -  "reuse" means
  reuse the *value* (or alias the legacy key), not that the strings match.
- Form-field labels often live in shared input-cell models, not the screen file  -  the Android layout is the
  reliable place to read them.
- Legacy values are backend-served  -  blank Old columns are an expected state, not an error. **Likewise blank
  CMS columns**  -  not every node is annotated yet.
- Error/validation/alert + dynamic keys are invisible to the static cross-reference  -  run
  `scan-screen-keys.py`, or they silently vanish from the map.
- **A rendered frame PNG is not guaranteed to share the frame's `absoluteBoundingBox` origin.**
  Building a `--spec` from REST geometry by subtracting the frame's absolute x/y from each text
  node's absolute x/y drifted every box by tens of pixels against the image the `/images`
  endpoint returned  -  boxes landed a row below their target, which looks plausible enough to
  ship and is wrong. Verify one crop by eye before trusting a batch, and prefer boxes read off
  the actual screenshot (the `--spec` path the skill documents) over coordinates derived from
  two different sources.
- **A key missing from the Suggested snapshot is not an unauthored key.** The snapshot is a
  generated mirror; upstream additions land in the shipped catalog first. Concluding "needs
  authoring" from the snapshot alone produced a batch of authoring requests for keys that were
  already live in all eight languages  -  the values were recoverable from the catalog the whole
  time. Pass `--catalog`, and when it answers, refresh the snapshot rather than filing anything.
- **Never anchor a keyshot by value across a whole file.** A row whose label isn't drawn on
  its own frames is tempting to recover by searching every frame for that text  -  but short
  labels ("Türkiye", "Cancel", "Continue") recur on unrelated screens, and the crop then
  boxes the wrong element with full confidence. That is strictly worse than "  -  ", because the
  content team believes it. Recover only via the row's own `cmsNodeId` (the node the content
  team annotated), and when you hand nodes to `render-key-shots --spec`, **omit
  `characters`**  -  with text present the renderer falls back to value matching and an
  unrelated row can bind to your node. "Text exists somewhere in the file" is not evidence
  that it is the same element.
- Confluence **Server/DC → Bearer PAT** (keychain `CONFLUENCE_API_TOKEN`) is not Cloud `user:token`; page
  lookup uses the DB-backed `content?title=` query, not CQL (CQL's index lags a fresh page → duplicate).
- Never commit a label-service token, Confluence PAT or Figma token into a mapping, a taxonomy file or these
  docs  -  keychain items and `--headers-file` exist for that.
