> ## Documentation Index > Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > These are Ditto's developer docs. Ditto is a single source of truth for product copy across design, review, localization, and code. > The first step on any codebase is a scan: https://developer.dittowords.com/get-started/scan-your-repo.md. That page also covers reviewing the style guide Ditto drafts from the scan. After it, the follow-on guides are Connect Figma files and Set up localization (under /guides/) and Connect the Ditto MCP (the Setup page of the MCP reference). > Two different MCP servers: the Ditto MCP server at https://api.dittowords.com/v2/mcp gives an agent a workspace's text and style guide rules; the documentation MCP server at https://developer.dittowords.com/mcp searches these docs. > Prefer logging in with a Ditto account (npx -y @dittowords/cli@latest login; OAuth in MCP clients) over API keys. API keys are for CI and headless clients only. > Commands are complete as written and use npx -y @dittowords/cli@latest; nothing needs a global install. # Scan your repo > Bring in your product's existing strings with one command. Once they're in, you can search, audit, and reuse the text from your live product. Let's bring in your product copy. One command scans your codebase and identifies your current product strings. Run it in your product's repo to import them; once they're in, you'll be able to search, audit, and reuse the text from your live product. ## Before you start You need Node.js 20 or newer (`node --version`) and a Ditto account ([app.dittowords.com](https://app.dittowords.com)). Scan the folder that holds your product's user-facing code, usually `./src`, `./app`, or the repo root on a small project. ## Run the scan Paste this prompt into Claude Code from the root of your repo. ```text theme={null} You're helping me set up Ditto on this codebase for the first time. Ditto manages the product copy, the words people read in this app. How to work with me: - Before you ask me to run, paste, click, or install anything, say in one plain sentence what it does and why, especially anything that opens a window or changes something on my machine. - One thing at a time. Ask, stop, wait for me. - Do the mechanical work yourself. Don't make me find links, pick folders, or assemble commands. SETUP, quietly, without stopping to ask me: 1. Check what OS I'm on and use it for every command you give me later. 2. The Ditto CLI needs Node 20 or newer. If mine is missing or too old, say what Node is and why the CLI needs it, walk me through installing it for my OS, then re-check. 3. Work out what we'd scan: run `pwd`, list the directory, run `git remote -v`, and read package.json. Pick the folder holding the app's user-facing code, usually ./src, ./app, or the repo root on a small project. Skip vendored and generated code. CHECK WITH ME, in a message with nothing else in it and no command yet: - Say what this app looks like ("this looks like your marketing site") and which part you'd scan, in plain words, with the folder name as supporting detail. - Ask whether that's the right product and the right part of it. If not, ask where the right thing lives and redo step 3. RUN THE SCAN. Run both commands yourself; my parts are confirming the folder and approving the sign-in. 1. Check whether DITTO_TOKEN is set in my environment. It's an API key and it outranks a browser sign-in, so leaving it set would scan into whichever workspace that key belongs to. If it's set, tell me and ask which to use. If I pick my own account, unset it for these commands only. 2. Tell me a browser tab is about to open for me to sign in to Ditto, then run: npx -y @dittowords/cli@latest login 3. Once I've approved it, scan the folder I confirmed: npx -y @dittowords/cli@latest scan 4. The scan is done as soon as it prints "Scan initiated!" and an app.dittowords.com/scan/... link. Stop there, give me the link, and tell me the rest happens on that page. If the scan exceeds my plan's limit, that's not a crash. Pick a smaller subfolder and try again, and tell me what you chose. ``` Paste this prompt into Cursor from the root of your repo. ```text theme={null} You're helping me set up Ditto on this codebase for the first time. Ditto manages the product copy, the words people read in this app. How to work with me: - Before you ask me to run, paste, click, or install anything, say in one plain sentence what it does and why, especially anything that opens a window or changes something on my machine. - One thing at a time. Ask, stop, wait for me. - Do the mechanical work yourself. Don't make me find links, pick folders, or assemble commands. SETUP, quietly, without stopping to ask me: 1. Check what OS I'm on and use it for every command you give me later. 2. The Ditto CLI needs Node 20 or newer. If mine is missing or too old, say what Node is and why the CLI needs it, walk me through installing it for my OS, then re-check. 3. Work out what we'd scan: run `pwd`, list the directory, run `git remote -v`, and read package.json. Pick the folder holding the app's user-facing code, usually ./src, ./app, or the repo root on a small project. Skip vendored and generated code. CHECK WITH ME, in a message with nothing else in it and no command yet: - Say what this app looks like ("this looks like your marketing site") and which part you'd scan, in plain words, with the folder name as supporting detail. - Ask whether that's the right product and the right part of it. If not, ask where the right thing lives and redo step 3. RUN THE SCAN. Run both commands yourself; my parts are confirming the folder and approving the sign-in. 1. Check whether DITTO_TOKEN is set in my environment. It's an API key and it outranks a browser sign-in, so leaving it set would scan into whichever workspace that key belongs to. If it's set, tell me and ask which to use. If I pick my own account, unset it for these commands only. 2. Tell me a browser tab is about to open for me to sign in to Ditto, then run: npx -y @dittowords/cli@latest login 3. Once I've approved it, scan the folder I confirmed: npx -y @dittowords/cli@latest scan 4. The scan is done as soon as it prints "Scan initiated!" and an app.dittowords.com/scan/... link. Stop there, give me the link, and tell me the rest happens on that page. If the scan exceeds my plan's limit, that's not a crash. Pick a smaller subfolder and try again, and tell me what you chose. ``` Paste this prompt into Codex from the root of your repo. ```text theme={null} You're helping me set up Ditto on this codebase for the first time. Ditto manages the product copy, the words people read in this app. How to work with me: - Before you ask me to run, paste, click, or install anything, say in one plain sentence what it does and why, especially anything that opens a window or changes something on my machine. - One thing at a time. Ask, stop, wait for me. - Do the mechanical work yourself. Don't make me find links, pick folders, or assemble commands. SETUP, quietly, without stopping to ask me: 1. Check what OS I'm on and use it for every command you give me later. 2. The Ditto CLI needs Node 20 or newer. If mine is missing or too old, say what Node is and why the CLI needs it, walk me through installing it for my OS, then re-check. 3. Work out what we'd scan: run `pwd`, list the directory, run `git remote -v`, and read package.json. Pick the folder holding the app's user-facing code, usually ./src, ./app, or the repo root on a small project. Skip vendored and generated code. CHECK WITH ME, in a message with nothing else in it and no command yet: - Say what this app looks like ("this looks like your marketing site") and which part you'd scan, in plain words, with the folder name as supporting detail. - Ask whether that's the right product and the right part of it. If not, ask where the right thing lives and redo step 3. RUN THE SCAN. Run both commands yourself; my parts are confirming the folder and approving the sign-in. 1. Check whether DITTO_TOKEN is set in my environment. It's an API key and it outranks a browser sign-in, so leaving it set would scan into whichever workspace that key belongs to. If it's set, tell me and ask which to use. If I pick my own account, unset it for these commands only. 2. Tell me a browser tab is about to open for me to sign in to Ditto, then run: npx -y @dittowords/cli@latest login 3. Once I've approved it, scan the folder I confirmed: npx -y @dittowords/cli@latest scan 4. The scan is done as soon as it prints "Scan initiated!" and an app.dittowords.com/scan/... link. Stop there, give me the link, and tell me the rest happens on that page. If the scan exceeds my plan's limit, that's not a crash. Pick a smaller subfolder and try again, and tell me what you chose. ``` Run this in your terminal from your product's repo. ```bash theme={null} npx -y @dittowords/cli@latest login npx -y @dittowords/cli@latest scan ./src ``` `login` opens a browser tab to sign in to Ditto. `scan` prints its progress and ends with a link: ```text theme={null} Scan initiated! Visit https://app.dittowords.com/scan/ to view progress and see results. ``` This only needs read access to your codebase. It won't edit or write to your repo. You'll be able to review what's scanned before bringing it into Ditto. Open the link. ## Review and refine Ditto classifies the strings and shows **Your codebase scan has finished!** with how many strings and locales it found. **Review scan** takes you through setting up your content system: 1. **Set up your content system in Ditto.** Ditto shows the unique and repeated strings it kept, the developer IDs it found, and your product name and blurb. Mark any strings to leave out or handle differently. 2. **Review proposed content system.** The tags Ditto will create, how it will give components names, how it will organize them, the variants and locales it found, and how it will name developer IDs, each with examples. Describe what you'd like to adjust, in plain language, until it looks right. 3. **Create.** Ditto creates the library components, variables, and one variant per locale. Home shows **Your product copy is now in Ditto!** with what was imported, and you can search and reuse what's live today across your product. ## Get a first style guide We can infer a starter style guide from your strings, or you can import your own. After a scan finishes, Ditto drafts a style guide with three sections: **Voice & Tone** and **Style & Mechanics** (rules) and a **Word List** (terminology). Each rule has a name, a description, and up to three from → to examples taken from your copy. Definitions: [Style guides and rules](/concepts#style-guides-and-rules). 1. In Ditto, open **Style guides** in the left sidebar. The inferred guide appears as a draft named after your product (or "Content Style Guide" if the name could not be inferred). 2. Open it. Edit, delete, or add rules, and move rules between sections. 3. Enable it. Turn on **Enabled by default** so it applies to every project, or enable it per project from the project's **…** menu under **Style guides**. Agents receive the rules through `get_styleguide_rules` as soon as the guide is enabled; the [PR review bot](/additional-tools/github-pr-review-bot) checks pull requests against them. To add, refine, or retire rules from your editor, see [Agent instructions](/guides/agent-instructions#turn-a-code-review-comment-into-a-rule). ## Frequently asked questions **What if my repo already has translation files?** Scan reads `strings.xml`, `.strings`, `.stringsdict`, `.xcstrings`, and JSON catalogs, and each locale becomes a variant in Ditto with that locale's text. **Is there a limit?** Trial workspaces can classify up to 1,000 strings in total across all of their scans. Paid plans have no cap. If a scan would exceed the remaining budget, the CLI stops before uploading and suggests subdirectories that fit.