---
name: localizeme
description: Move copy between this Figma file and LocalizeMe through the LocalizeMe connector. Use it whenever the user wants a frame shown in another language, wants new text saved as translation keys, or wants a screenshot of a frame attached to the keys it shows.
---

# LocalizeMe copy sync

LocalizeMe stores translation keys per project. Every key has a value per
language, and every tool call needs a `project_id`: call `list_projects` once,
pick the project the user names (ask if more than one fits), and reuse the id
for the rest of the conversation.

## Pull a language into the selection

Trigger: the user asks to see a frame in a language, fill a frame with the
real copy, or switch the selection to German, French, and so on.

1. Read every text layer inside the selected frames: its name and its current
   characters.
2. Call `list_keys` for the project with `include_translations` on. Page
   through with `offset` while `has_more` is true.
3. Match each text layer to one key, trying these in order and stopping at the
   first that yields exactly one key:
   a. the layer name equals the key name;
   b. the layer's text equals that key's value in the project's source
      language;
   c. the layer's text equals that key's value in any other project language,
      so a frame already switched to German still matches.
   Trim whitespace and ignore case throughout. If a step matches more than one
   key, do not pick one — the same words often appear under several keys, and
   a word like "Total" can be identical in two languages. Carry on to the next
   step, and if the ambiguity survives, leave the layer alone and list it as
   ambiguous with the keys it could have been. Never guess.
4. Replace the characters of each matched layer with the requested language's
   value for platform `all`, unless the user names a platform. Keep font, size,
   colour and layout exactly as they are. If the new text no longer fits, say
   so; do not resize anything.
5. Rename each matched layer to its key name, unless it already is. Figma
   names a text layer after its content until someone renames it, so without
   this step the name silently becomes the German text and the key is visible
   nowhere in the file. With it, every synced string shows its key in the
   Layers panel for anyone who opens the file, and later pulls match by name.
6. Report three lists: layers updated, layers with no key, and keys whose
   value in that language is still missing.

## Push new text as keys

Trigger: the user asks to create keys for text in the frame, to send copy to
LocalizeMe, or to save the strings.

1. Skip layers that are not copy: prices, dates, sample names and addresses,
   lorem ipsum, or anything that is only digits and symbols.
2. For each remaining layer that matched nothing in a pull, propose a key name
   as `<frame>.<text>`: the frame name in lower snake_case, then the layer's
   text in lower snake_case with punctuation dropped, for example
   `checkout.continue_shopping`. Show the list and wait for a yes before
   writing anything.
3. Create each key with `create_key`: the key name, the layer's text as the
   project's source-language value, and the frame name as the description so
   a translator knows which screen it is on.
4. Pass `design_url` too, so the key links back to the design. Use the id of
   the **frame**, not of the text layer inside it — the frame is the view a
   translator wants. Build it as
   `https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>` where:
   - `<nodeId>` is the frame's id with its colon written as a hyphen, so `1:2`
     becomes `1-2`;
   - `<fileName>` must be URL-safe. A Figma file is usually named with spaces
     ("Checkout flow"), and a space is not valid in a URL, so replace runs of
     whitespace with single hyphens and drop any character that is not a
     letter, digit, hyphen or underscore. "Checkout flow" becomes
     `Checkout-flow`. Sending the raw name makes the link invalid.
   If you are unsure of the file name, omit that segment entirely rather than
   guessing: `https://www.figma.com/design/<fileKey>?node-id=<nodeId>` still
   opens the right node.
5. Rename each layer to its key name, so the next pull matches by name.
6. Only when the user asks for it: a screenshot has to travel through this
   conversation as base64, and Figma's sandbox makes that slow and often
   fails outright. Export at 1x, keep it under 1.5 MB, and call
   `upload_screenshot` with the frame name and the keys it shows. Try once.
   If it does not go through, say so plainly and suggest dragging the frame
   into the project's Screenshots tab in the dashboard instead. Never retry
   in a loop.

## Rules

- Never overwrite a translation from Figma. If a key already has a
  source-language value that differs from the layer text, report the
  difference and ask which one is right.
- Never delete keys, translations or projects.
- Map language names to the project's codes (German is `de`). If the language
  is not enabled on the project, say so instead of adding it.
- Write only to the project the user named. If nothing was named and the
  account has several projects, ask before the first write.