> ## 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. # Developer changelog > Release notes for the Ditto API, CLI, MCP server, GitHub Action, and React SDK, newest first. ## October 7, 2026 ### API Add `newDeveloperId` to [Update a style guide](https://developer.dittowords.com/api-reference/styleguides/patch-styleguides) (`PATCH /v2/styleguides`) for renaming a style guide's developer ID. It can be set alongside other field changes in the same request, and must be unique among the workspace's style guides. ### MCP Add `newDeveloperId` to the [`update_styleguide`](/mcp-reference/tools#update_styleguide) tool for renaming a style guide's developer ID. It can be combined with other field changes in the same call. ## October 5, 2026 ### API Improvements to plural exports for json formats. * `json_i18next` Now returns the unsuffixed key alongside all plural keys. This brings it in line with what the CLI exports for `json` and `json + i18next`. * `json_vue_i18n` Resolves a minor bug in how plurals were generated if you had a `zero` and `other` form defined but not a `one` form. This format still drops `two`, `few`, and `many` forms, which are not supported by Vue without a custom rule definition. This change is not yet reflected in the CLI. ## October 1, 2026 ### MCP Add the [`translate_text_items`](/mcp-reference/tools#translate_text_items) tool for translating project text items into a variant's locale, applying any style guide scoped to that locale. Add the [`translate_library_components`](/mcp-reference/tools#translate_library_components) tool for translating library components into a variant's locale, applying any style guide scoped to that locale. ## September 17, 2026 ### Ditto CLI - 5.10.0 [`scan`](/cli-reference/commands#scan) now requires a clean checkout of your repository's default branch. Scanning from a tree with uncommitted changes, from a non-default branch, or from a detached `HEAD` stops with a message explaining what to change, before anything is uploaded. Scan records the commit and branch it read, and the code links Ditto builds point at them. A scan taken from anywhere else describes lines your default branch never had, so a later scan reports those links as changed or removed when nothing actually changed. The default branch comes from `origin/HEAD`, falling back to a local `main` or `master`. Because that reference is set when you clone and doesn't update on its own, a mismatch is confirmed against your remote first, so a branch renamed after you cloned won't block you. Scanning outside a Git repository is unaffected. ## September 3, 2026 ### API Add [Publish component](https://developer.dittowords.com/api-reference/components/publish-component) (`POST /v2/components/publish`) endpoint for publishing an existing text item to the component library. Add [Link components](https://developer.dittowords.com/api-reference/components/link-components) (`PATCH /v2/components/link`) endpoint for linking text items to a library component by developer ID. Add [Unlink components](https://developer.dittowords.com/api-reference/components/unlink-components) endpoint, which unlinks every text item that currently shares a given developer ID with its sibling instances. Accepts an optional `projectId` to scope the unlink to a single project. ### MCP Add the [`publish_library_component`](/mcp-reference/tools#publish_library_component) for publishing an existing text item to the component library. Add the [`link_text_items_to_component`](/mcp-reference/tools#link_text_items_to_component) for linking text items to a library component by developer ID. Add the [`unlink_text_items_from_component`](/mcp-reference/tools#unlink_text_items_from_component) tool, which unlinks every text item that currently shares a given developer ID with its sibling instances. Accepts an optional `projectId` to scope the unlink to a single project. ## August 27, 2026 ### API Add [ARB](https://github.com/google/app-resource-bundle/wiki/ApplicationResourceBundleSpecification) as an export format for [Export text items](https://developer.dittowords.com/api-reference/text-items/export-text-items) (`GET /v2/textItems/export`) and [Export components](https://developer.dittowords.com/api-reference/components/export-components) (`GET /v2/components/export`) — provide `?format=arb`. See [ARB JSON](/string-formats/json#arb-json) for the content shape. ### Ditto CLI - 5.9.0 Add `framework: arb` and `framework: icu` for `json`-format outputs, generating [ARB](/string-formats/json#arb-json) and [ICU](/string-formats/json#icu-json) JSON respectively. See [Frameworks](/cli-reference/files#framework-specific-files). Add [`androidLocales`](/cli-reference/configuration#androidlocales), which maps Ditto variant IDs to Android locale-qualified resource directories (`values-/`) — the Android counterpart to `iosLocales`. Unlike `iosLocales`, there's no need to map `base`, since Android already has a default resource directory (`values/`) that the platform falls back to automatically. Add [`androidLocalesOutDir`](/cli-reference/configuration#androidlocalesoutdir) and [`iosLocalesOutDir`](/cli-reference/configuration#ioslocalesoutdir), which let Android and iOS locale-organized output be written to separate root directories — useful since they typically need to live in different parts of a codebase. ## August 24, 2026 ### Ditto CLI - 5.8.1 [`scan`](/cli-reference/commands#scan) now records which part of your repository it looked at, alongside the Git context added in 5.8.0. Scanning a repository root is recorded as covering the whole repository; scanning a single directory is recorded as covering only that directory. This lets Ditto tell the difference between a string removed from your code and a string that simply was not part of the scan, so re-scanning one directory implies nothing about the rest of the repository. ## August 20, 2026 ### Ditto CLI - 5.8.0 [`scan`](/cli-reference/commands#scan) now records the Git repository, commit, and branch of the code it scans. Ditto uses these to recognize a codebase it has already seen, so a later scan of the same repository can be matched against an earlier one instead of importing every string again. This is read from your local Git checkout. Scan makes no additional network requests, does not send Git credentials, and records nothing about your remote beyond its host and path. Scanning outside a Git repository still works — the CLI notes that the scan can be imported but not re-synced, and continues. ## August 18, 2026 ### Ditto CLI - 5.7.2 Move [`scan`](/cli-reference/commands#scan) text extraction into the shared `@dittowords/text-extract` library. Extraction behavior is unchanged. ## August 17, 2026 ### API Add `richText` parameter to [Create components](https://developer.dittowords.com/api-reference/components/create-components) (`POST /v2/components`) and [Patch components](https://developer.dittowords.com/api-reference/components/patch-components) (`PATCH /v2/components`). When `richText` param is set to `html`, all text values in the update request — including plural and variant text — will be parsed as an HTML string and saved as rich text. ## August 13, 2026 ### Ditto CLI - 5.7.1 Improve how [`scan`](/cli-reference/commands#scan) decodes the text it extracts. Escape sequences, XML entities, and inline markup are now handled per file format, so candidates arrive in Ditto as the text a user sees instead of as raw source. ### MCP Add the [`list_statuses`](/mcp-reference/tools#list_statuses) tool, which lists the statuses text items and library components can be set to, in workflow order. The MCP server now supports logging in with your Ditto account via OAuth, in addition to a static API token. See [Installation](/guides/connect-the-mcp) for setup instructions per client. ### API Add [Delete components](https://developer.dittowords.com/api-reference/components/delete-components) (`DELETE /v2/components`) endpoint for deleting library components by developer ID. Add [Fetch statuses](https://developer.dittowords.com/api-reference/statuses/get-statuses) (`GET /v2/statuses`) endpoint for listing the statuses available in a workspace, in workflow order. ## August 11, 2026 ### API Add `richText` parameter to [Update text items](https://developer.dittowords.com/api-reference/text-items/patch-text-items) (`PATCH /v2/textItems`) and [Create text items](https://developer.dittowords.com/api-reference/text-items/create-text-items) (`POST /v2/textItems`). When `richText` param is set to `html`, all `text` values in the update request — including plural and variant text — will be parsed as an HTML string and saved as rich text. For example, the following request would store formatted string "**Inspiration** for your next trip" as the Korean variant: ```json theme={null} { "richText": "html", "variantId": "korean", "updates": [ { "developerId": "homepage.section.inspiration", "text": "Inspiration for your next trip" } ] } ``` * Supported formatting: ``/``, ``/``, ``, ``, and `
` for line breaks. * `` and `` are only supported for workspaces with superscript and subscript enabled. * We drop unsupported markup such as links, lists, or headings but keep its text. * `{{variable_name}}` placeholders still resolve, and keep any formatting applied around them. * Without the parameter, text is saved as plaintext and any markup is stored literally, unchanged from previous behavior. ## August 10, 2026 ### MCP Add [`create_variables`](/mcp-reference/tools#create_variables), [`update_variables`](/mcp-reference/tools#update_variables), and [`delete_variables`](/mcp-reference/tools#delete_variables) tools for managing variables from your editor. ### API Add [Create variables](https://developer.dittowords.com/api-reference/variables/create-variables) (`POST /v2/variables`), [Update variables](https://developer.dittowords.com/api-reference/variables/patch-variables) (`PATCH /v2/variables`), and [Delete variables](https://developer.dittowords.com/api-reference/variables/delete-variables) (`DELETE /v2/variables`) endpoints. * Renaming a variable with `newName` rewrites every `{{variable_name}}` placeholder referencing it — across text items, library components, variants, and plurals — so existing text keeps resolving. * A variable can't be deleted while any text item or library component still references it. ## August 6, 2026 ### MCP Add [`create_variants`](/mcp-reference/tools#create_variants), [`update_variants`](/mcp-reference/tools#update_variants), and [`delete_variants`](/mcp-reference/tools#delete_variants) tools for managing variants from your editor. ### API Add [Create variants](https://developer.dittowords.com/api-reference/variants/create-variants) (`POST /v2/variants`), [Update variants](https://developer.dittowords.com/api-reference/variants/patch-variants) (`PATCH /v2/variants`), and [Delete variants](https://developer.dittowords.com/api-reference/variants/delete-variants) (`DELETE /v2/variants`) endpoints. * At most one variant per workspace can hold a given locale code. * A variant can't be deleted while any text item or library component still has text for it. ## August 5, 2026 ### Ditto CLI - 5.7.0 Add the [`login`](/cli-reference/commands#login) and [`logout`](/cli-reference/commands#logout) commands. `login` signs you in through your browser, so the CLI no longer needs an API key. ```bash theme={null} npx @dittowords/cli login ``` * The session is saved to `$HOME/.config/ditto` and renews itself as you keep using the CLI. Commands act as you — your Ditto account and its permissions — instead of as whoever generated an API key. * `logout` forgets the session on this machine and revokes it with Ditto. * API keys still work. `DITTO_TOKEN` takes precedence over a saved session, so CI and other headless environments are unaffected. See [credential precedence](/cli-reference/authentication#credential-precedence). ## August 3, 2026 ### MCP Add [`create_styleguide`](/mcp-reference/tools#create_styleguide), [`list_styleguides`](/mcp-reference/tools#list_styleguides), and [`update_styleguide`](/mcp-reference/tools#update_styleguide) tools for managing style guides themselves — sections, the default-enabled setting, and metadata — as opposed to the rules inside them. Add [`create_styleguide_rules`](/mcp-reference/tools#create_styleguide_rules), [`update_styleguide_rules`](/mcp-reference/tools#update_styleguide_rules), and [`delete_styleguide_rules`](/mcp-reference/tools#delete_styleguide_rules) tools for managing the rules inside a style guide section. Add [`list_component_folders`](/mcp-reference/tools#list_component_folders), [`create_component_folders`](/mcp-reference/tools#create_component_folders), [`update_component_folders`](/mcp-reference/tools#update_component_folders), and [`delete_component_folders`](/mcp-reference/tools#delete_component_folders) tools for managing component library folders from your editor. ### API Add [Create a style guide](https://developer.dittowords.com/api-reference/styleguides/create-styleguides) (`POST /v2/styleguides`) and [Update a style guide](https://developer.dittowords.com/api-reference/styleguides/patch-styleguides) (`PATCH /v2/styleguides`) endpoints, along with [Create style guide rules](https://developer.dittowords.com/api-reference/styleguides/create-styleguide-rules) (`POST /v2/styleguides/rules`), [Update style guide rules](https://developer.dittowords.com/api-reference/styleguides/patch-styleguide-rules) (`PATCH /v2/styleguides/rules`), and [Delete style guide rules](https://developer.dittowords.com/api-reference/styleguides/delete-styleguide-rules) (`DELETE /v2/styleguides/rules`) endpoints for managing the rules inside a section. Add [Fetch component folders](https://developer.dittowords.com/api-reference/component-folders/get-component-folders) (`GET /v2/componentFolders`), [Create component folders](https://developer.dittowords.com/api-reference/component-folders/create-component-folders) (`POST /v2/componentFolders`), [Update component folders](https://developer.dittowords.com/api-reference/component-folders/patch-component-folders) (`PATCH /v2/componentFolders`), and [Delete component folders](https://developer.dittowords.com/api-reference/component-folders/delete-component-folders) (`DELETE /v2/componentFolders`) endpoints. ## July 31, 2026 ### MCP Add the [`suggest_edit`](/mcp-reference/tools#suggest_edit) tool, which checks text against your workspace's style guide rules and returns suggested edits — the same rule-based suggestions shown in the Ditto app. Check an existing text item by developer ID, or freeform text that isn't saved as a text item yet. ## July 29, 2026 ### MCP Add [`list_project_blocks`](/mcp-reference/tools#list_project_blocks), [`create_project_blocks`](/mcp-reference/tools#create_project_blocks), [`update_project_blocks`](/mcp-reference/tools#update_project_blocks), and [`delete_project_blocks`](/mcp-reference/tools#delete_project_blocks) tools for managing the blocks that group text items within a project. ### API Add [Fetch project blocks](https://developer.dittowords.com/api-reference/project-blocks/get-project-blocks) (`GET /v2/projectBlocks`), [Create project blocks](https://developer.dittowords.com/api-reference/project-blocks/create-project-blocks) (`POST /v2/projectBlocks`), [Update project blocks](https://developer.dittowords.com/api-reference/project-blocks/patch-project-blocks) (`PATCH /v2/projectBlocks`), and [Delete project blocks](https://developer.dittowords.com/api-reference/project-blocks/delete-project-blocks) (`DELETE /v2/projectBlocks`) endpoints. ## July 27, 2026 ### Ditto CLI - 5.6.3 Improve how [`scan`](/cli-reference/commands#scan) handles codebases that are larger than a workspace's plan's scan limit. Add the `--list-directories` flag. `scan --list-directories` prints the number of candidate strings found in each directory and exits without uploading anything, so you can choose a scope before running a real scan. ```bash theme={null} npx @dittowords/cli scan . --list-directories ``` * Counts are rolled up: each directory includes the strings found in its subdirectories. * Directories are printed in tree order, indented by depth, with the whole scan total at the top. When a scan exceeds your plan's limit, the error now suggests narrower paths to scan instead of just reporting the limit. * The message lists the largest subdirectories that each fit within your remaining limit, with their string counts and a ready-to-run command for each. * The limit is checked before candidates are uploaded, so an oversized scan fails right away instead of after the upload finishes. ### MCP Add the [`create_ditto_project`](/mcp-reference/tools#create_ditto_project) and [`list_project_folders`](/mcp-reference/tools#list_project_folders) tools for creating projects and looking up project folders from your editor. ### API Add [Create a project](https://developer.dittowords.com/api-reference/projects/create-projects) (`POST /v2/projects`) endpoint. Optionally provide a folder's developer ID to create the project inside that folder. ## July 24, 2026 ### MCP Add [`create_library_components`](/mcp-reference/tools#create_library_components) and [`update_library_components`](/mcp-reference/tools#update_library_components) tools for managing library components from your editor, and the [`list_component_folders`](/mcp-reference/tools#list_component_folders) tool for looking up their folders. ## July 22, 2026 ### Documentation Document the [agent setup package](https://github.com/dittowords/ditto-agent-setup) as the default way to integrate Ditto with Claude Code. See [Agent setup package](/guides/connect-the-mcp). Standardize the API token environment variable to `DITTO_TOKEN` across the CLI, Ditto Specs, and MCP setup docs (previously `DITTO_API_KEY` and `DITTO_API_TOKEN`). ### MCP Add [`list_variants`](/mcp-reference/tools#list_variants) and [`list_variables`](/mcp-reference/tools#list_variables) tools, and expose variants and variables on the text item and library component tools — reference a variable with a `{{variable_name}}` placeholder, or set variant-specific text via a variant's developer ID. ## July 10, 2026 ### MCP Add [`create_text_items`](/mcp-reference/tools#create_text_items), [`update_text_items`](/mcp-reference/tools#update_text_items), and [`delete_text_items`](/mcp-reference/tools#delete_text_items) tools for managing text items in bulk from your editor, and the [`list_projects`](/mcp-reference/tools#list_projects) tool for looking up a project's developer ID. ## July 9, 2026 ### API Add [Fetch activity](https://developer.dittowords.com/api-reference/activity/get-activity) (`GET /v2/activity`) endpoint for retrieving a paginated list of change events in your workspace, optionally filtered by project, text item, library component, or entity type. ## July 1, 2026 ### API Add `blockName` field to [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) response. * Each text item now includes a `blockName` field: the name of the block the text item belongs to, or `null` if it is not in a block. ## June 25, 2026 ### API Add `sort` parameter to [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`). * `id` (default) sorts the response alphabetically by developer ID (matching previous behavior) * `project_order` groups items by project, returned alphabetically by project developer ID, then sorts within projects based on the custom sort order set up in the web app. ## June 16, 2026 ### Ditto CLI - 5.6.0 Add the `scan` command. `scan ` analyzes a local directory for user-facing text and sends the candidates to Ditto, where you can review them and turn them into a content system tailored to your product. See the [Scan documentation](/cli-reference/commands#scan). * This release includes packages that require **Node.js 20 or higher**. ## June 10, 2026 ### API Add new variant fields `variants[n].status`, `variants[n].assignee`, `variants[n].notes`, and `variants[n].characterLimit` to the [Create text items](https://developer.dittowords.com/api-reference/text-items/create-text-items) resource. * `assignee` must be a valid email matching a user in your workspace * variant `status` must be a valid status in your workspace ## June 4, 2026 ### API Add `folderId` to the [Update components](https://developer.dittowords.com/api-reference/components/patch-components) resource, allowing users to organize their components in bulk. * If `folderId` of `null` or `"root"` is provided, will move component into "All Components". * If `folderId` omitted, component folder will remain unchanged Add [Get style guides](https://developer.dittowords.com/api-reference/styleguides/get-styleguides) (`GET /v2/styleguides`) endpoint for fetching the style guides created in your workspace, along with their sections and rules. ## May 28, 2026 ### API Add `assignee`, along with new variant fields `variants[n].status`, `variants[n].assignee`, `variants[n].notes`, and `variants[n].characterLimit` to the [Create components](https://developer.dittowords.com/api-reference/components/create-components) resource. * `assignee` must be a valid email matching a user in your workspace * variant `status` must be a valid status in your workspace ## May 18, 2026 ### API Add `characterLimit` field to [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) and [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`) responses. * Each text item and component in the response now includes a `characterLimit` field: a positive integer when a limit is set, or `null` when no limit is configured. * For variant responses, `characterLimit` reflects the variant's own character limit rather than the base value. ## May 12, 2026 ### API Update Text Item and Component endpoints to support variant assignee, notes and character limit. * [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) and [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`) now return variant assignee and notes in variant response objects, not the base properties. * Requests that include an assignee filter and a variantId return only items whose base and variant assignees both match the filter. This applies to [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`), [Export text items](https://developer.dittowords.com/api-reference/text-items/export-text-items) (`GET /v2/textItems/export`), [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`), and [Export components](https://developer.dittowords.com/api-reference/components/export-components) (`GET /v2/components/export`). * Requests that include assignee, notes and/or character limit along with a variantId in the payload of [Update text items](https://developer.dittowords.com/api-reference/text-items/patch-text-items) (`PATCH /v2/textItems`) or [Update components](https://developer.dittowords.com/api-reference/components/patch-components) (`PATCH /v2/components`) will update that variant's properties, not the base values. ## April 30, 2026 ### API Add component name to the response of [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`) endpoint. Each component in the response will now include a `name` field matching the component name. The same component name will be returned across base text, variants and plural forms. ## April 6, 2026 ### API Add [Update components](https://developer.dittowords.com/api-reference/components/patch-components) (`PATCH /v2/components`) endpoint. Supports updating text, tags, status, and assignee on components identified by developer ID. Includes optional variant targeting with `variantId` and `forceVariantCreation` parameters. Add `PATCH /v2/textItems` as the preferred method for updating text items. `PUT /v2/textItems` continues to work but is now deprecated. ## April 1, 2026 ### Ditto CLI - 5.5.1 Dependency updates and internal improvements. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.5.1). ## March 31, 2026 ### Ditto CLI - 5.5.0 Add CLI support for filtering by tags. Add a `tags` configuration to your config file to scope text items and components by one or more tags, with support for `AND`/`OR` operators. ```yaml theme={null} tags: values: - "tag-1" - "tag-2" operator: "AND" ``` The `tags` filter can be specified at the top level of your config or within individual outputs (output-level overrides top-level). When `operator` is `"AND"`, only items with all specified tags are returned. When `operator` is `"OR"` (or omitted), items with any of the specified tags are returned. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.5.0). ## March 27, 2026 ### MCP Add the [`get_workspace_tags`](/mcp-reference/tools#get_workspace_tags) tool, which lists the tags currently in use across the workspace — useful before adding tags to a style guide rule, since only existing tags are allowed. Add the first tools for creating, updating, and deleting style guide rules from your editor. ## March 26, 2026 ### API Add `assignee` and `tags` filters to [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`), [Export components](https://developer.dittowords.com/api-reference/components/export-components) (`GET /v2/components/export`), and [Export text items](https://developer.dittowords.com/api-reference/text-items/export-text-items) (`GET /v2/textItems/export`). The `assignee` filter accepts an email address or `null` to match unassigned items. The `tags` filter accepts an array of tag values with an optional `operator` field (`AND` or `OR`, defaulting to `OR`). ## March 24, 2026 ### Ditto CLI - 5.4.0 Add CLI support for filtering by integration status. Add `integrated: true` to your config file to fetch only text items and components that have been marked as integrated into development. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.4.0). ### API Add the ability to update the `integrated` flag of a text item via [Update text items](https://developer.dittowords.com/api-reference/text-items/update-text-items) (`PUT /v2/textItems`). ## March 23, 2026 ### API Add `integrated` field to the response data of: * [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) * [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`). Add optional `integrated` boolean filter to: * [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) * [Export text items](https://developer.dittowords.com/api-reference/text-items/export-text-items) (`GET /v2/textItems/export`) * [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`) * [Export components](https://developer.dittowords.com/api-reference/components/export-components) (`GET /v2/components/export`) ## March 20, 2026 ### MCP The Ditto MCP server can now run remotely over Streamable HTTP, instead of only as a local stdio server. See [Installation](/guides/connect-the-mcp) for how to connect Claude Code, Cursor, VS Code, Windsurf, Codex, and other MCP clients. ## March 19, 2026 ### API Add `plurals` field to [Update text items](https://developer.dittowords.com/api-reference/text-items/update-text-items) (`PUT /v2/textItems`) API endpoint. The `plurals` field supports `upsert` and `remove` operations for managing plural forms (zero, one, two, few, many, other) on text items. Existing plural forms not mentioned in either operation are preserved. Supports variant plurals via the `variantId` parameter. ## March 18, 2026 ### API Add `assignee` and `tags` filters to [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`). The `assignee` filter accepts an email address or `null` to match unassigned text items. The `tags` filter accepts an array of tag values with an optional `operator` field (`AND` or `OR`, defaulting to `OR`). [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) and [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`) now include the `assignee` field in the response payload, returned as the assignee's email address or `null` if unassigned. ## March 16, 2026 ### API Add `assignee` field to [Update text items](https://developer.dittowords.com/api-reference/text-items/update-text-items) (`PUT /v2/textItems`) API endpoint. The `assignee` field accepts an optional email string of a user in the workspace to assign to the text item. Setting `assignee` to `null` will remove the current assignee. ## March 12, 2026 ### MCP Add the [`search_ditto_text`](/mcp-reference/tools#search_ditto_text) tool, which searches your workspace for existing text items and library components by content — so agents can find and reuse strings instead of generating new ones. ## March 5, 2026 ### MCP Ditto's MCP server is here! It connects AI coding agents to your team's content in Ditto, starting with the [`get_styleguide_rules`](/mcp-reference/tools#get_styleguide_rules) tool for fetching workspace and project-level style guide rules. See the [MCP overview](/mcp-reference/overview) to get started. ## February 10, 2026 ### API Add [Create components](https://developer.dittowords.com/api-reference/components/create-components) (`POST /v2/components`) endpoint for creating new library components. ## February 2, 2026 ### API [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`), [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`), [Export text items](https://developer.dittowords.com/api-reference/text-items/export-text-items) (`GET /v2/textItems/export`), and [Export components](https://developer.dittowords.com/api-reference/components/export-components) (`GET /v2/components/export`) now return a `400` error response when statuses that don't exist in your workspace are provided in the status filter. ## January 14, 2026 ### API [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) and [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`) now return separate records for each plural form. Plural forms follow the standard i18n plural forms outlined [here](https://www.i18next.com/translation-function/plurals). Each record in the response includes a `pluralForm` value, and for each `pluralForm` on a text item or component, a separate record is returned with that `pluralForm` and its respective value. If a record has a `pluralForm`, it will be appended to the end of the developer ID. Example response: ```json theme={null} [ { "id": "some-items", "text": "Some items", "pluralForm": null, ... }, { "id": "some-items_other", "text": "Some items", "pluralForm": "other", ...}, { "id": "some-items_one", "text": "An item", "pluralForm": "one", ... } ] ``` ### Ditto CLI - 5.3.1 Default [JSON file formats](https://developer.dittowords.com/cli-reference/files#json) now include plurals, where the standard unicode plural rule (zero, one, two, few, many, other) is appended to the end of the developer ID key. Example output: ```json theme={null} { "some-items": "Some items", "some-items_one": "An item", "some-items_other": "{{count}} items" } ``` See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.3.1). ## January 7, 2026 ### API Add [Export text items](https://developer.dittowords.com/api-reference/text-items/export-text-items) (`GET /v2/textItems/export`) and [Export components](https://developer.dittowords.com/api-reference/components/export-components) (`GET /v2/components/export`) endpoints for fetching text items and components in `.json` ICU, `.json` i18next, `.json` Vue i18n, `.strings`, `.stringsdict`, or `.xml` formats. ### Ditto CLI - 5.3.0 Add CLI support for Android `.xml`, iOS `.strings` and `.stringsdict`, and ICU `.json` formats. In conjunction with iOS format additions, add iOS Locale directory generation for configured variant -> locale mappings in config. If iOS locales are configured, CLI will also auto-generate a Ditto.swift file for reading locale values. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.3.0). ## December 11, 2025 ### Ditto CLI - 5.2.0 Add CLI support for filtering [text items/components by status](/cli-reference/configuration#statuses) when pulling changes. The filtering logic used for the cli is the same as the [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) and the [Fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`) API endpoints. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.2.0). ## December 10, 2025 ### API Relax requirement in [Update text items](https://developer.dittowords.com/api-reference/text-items/update-text-items) (`PUT /v2/textItems`) API endpoint that requires text to be included in the request. Add `tags` field which is an optional `string[]` that if set in the request will replace the existing tags with the specified tags on the textItem. ## December 9, 2025 ### API Clarified expected behavior with variant and status filtering for [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) API endpoint. Variants that match the variant filter should only be returned if they match the status filter and their base text also matches the status filter. Added query param in [Fetch components](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/components`) API endpoint status filter that allows for filtering components by status. Variants that match the variant filter should only be returned if they match the status filter and their base text also matches the status filter. ## December 5, 2025 ### API Added [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) API endpoint status filter that allows for fetching textItems by status. Relax requirement in [Update text items](https://developer.dittowords.com/api-reference/text-items/update-text-items) (`PUT /v2/textItems`) API endpoints that requires all textItems to be in the same project. Now updates can include textItems that span multiple projects and all will be updated. ### Documentation Fix env var naming used in the cli for setting the ditto api token to the correct value `DITTO_TOKEN` ## November 5, 2025 ### API Added [delete text items](https://developer.dittowords.com/api-reference/text-items/delete-text-items) (`DELETE /v2/textItems`) API endpoint for deleting text items. ## October 6, 2025 ### Ditto Github Action - 1.0.2 Updates the Github Action to work with CLI `v5.x`, compatible with both new and legacy Ditto. After upgrading, the Github Action will fetch from new Ditto projects/components by default. Legacy users will need to add `pull-from-legacy: "true"` to their workflow file to continue fetching legacy text. If you wish to use this action for both new and legacy Ditto, simply create separate steps with different inputs. See the [README](https://github.com/marketplace/actions/ditto-github-action) for more details and examples. Release notes: * [1.0.2](https://github.com/dittowords/ditto-github-action/releases/tag/v1.0.2) * [1.0.1](https://github.com/dittowords/ditto-github-action/releases/tag/v1.0.1) * [1.0.0](https://github.com/dittowords/ditto-github-action/releases/tag/v1.0.0) ### Ditto CLI - 5.1.0 A small update to support the `-m` and `--meta` flags in commands. This is used internally for analytics and should not affect customer workflows. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.1.0). ## October 1, 2025 ### Ditto CLI - 5.0.0 First official stable release that provides support for fetching project text and components from the new Ditto experience, including all features from the v5 Beta release (through 5.0.0-beta.8). This version maintains full support for fetching from legacy projects and components. Simply include the `--legacy` flag along with any command from `v4.x`. Users with both new and legacy projects may pull data from both places into the same codebase by maintaining two separate config files and output directories, and including the path to the right config file in your pull command. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.0.0). ## September 29, 2025 ### API Added [fetch components](https://developer.dittowords.com/api-reference/components/get-components) (`GET /v2/components`) API endpoint for fetching components in the user's workspace. ### Ditto CLI - 5.0.0-beta.8 Added support for fetching components in addition to project text via the CLI. Include `components` in your config file to fetch components from the specified folders. Include `projects` in your config file to fetch text from the specified projects. **Breaking change:** If `projects` or `components` are omitted from the config file, will not fetch text from that area. Previously, if `projects` was omitted, it would fetch text from all projects. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.8). ## September 11, 2025 ### API Added the ability to create variants from [update text items](https://developer.dittowords.com/api-reference/text-items/update-text-items#body-force-variant-creation) (`PUT /v2/textItems`) API endpoint with the `forceVariantCreation` parameter. ## August 18, 2025 ### Ditto CLI - 5.0.0-beta.7 Added support for fetching and outputting rich text (HTML) content for Ditto text, by adding `richText: html` to the config file. At this time, this version is still in Beta, accessible via `@dittowords/cli@beta`. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.7). ## July 24, 2025 ### API Added [create text items](https://developer.dittowords.com/api-reference/text-items/create-text-items) (`POST /v2/textItems`) API endpoint for creating new text items. ## July 8, 2025 ### API Added [update text items](https://developer.dittowords.com/api-reference/text-items/update-text-items) (`PUT /v2/textItems`) API endpoint for editing existing text items. ## April 30, 2025 ### Ditto CLI - 5.0.0-beta.6 Beta release of CLI for Ditto 2.0. This version supports fetching text from new, non-legacy Ditto projects. It requires a new format for the config file and supports returning json files formatted for i18next. This version is still in beta, and can be accessed via `@dittowords/cli@beta`. Supports all legacy features via `--legacy` flag. Release notes: * [5.0.0-beta.6](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.6) * [5.0.0-beta.5](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.5) * [5.0.0-beta.4](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.4) * [5.0.0-beta.3](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.3) * [5.0.0-beta.2](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.2) * [5.0.0-beta.1](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.1) * [5.0.0-beta.0](https://github.com/dittowords/cli/releases/tag/v5.0.0-beta.0) ## March 28, 2025 ### API * Added [fetch project folders](https://developer.dittowords.com/legacy/api-reference-legacy/project-folders/fetch-project-folders) (`GET /v1/project-folders`) API endpoint for fetching project folders in the user's workspace. * Added [fetch projects by project folder id](https://developer.dittowords.com/legacy/api-reference-legacy/project-folders/fetch-projects-by-project-folder-id) (`GET /v1/project-folders/:folder_id/projects`) API endpoint for fetching projects in the specified folder. ## March 24, 2025 ### API Added the first set of v2 endpoints to the API: * Added [fetch projects](https://developer.dittowords.com/api-reference/projects/get-projects) (`GET /v2/projects`) API endpoint for fetching projects in the user's workspace. * Added [fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items) (`GET /v2/textItems`) API endpoint for fetching text items in the user's workspace. * Added [fetch variables](https://developer.dittowords.com/api-reference/variables/get-variables) (`GET /v2/variables`) API endpoint for fetching variables in the user's workspace. * Added [fetch variants](https://developer.dittowords.com/api-reference/variants/get-variants) (`GET /v2/variants`) API endpoint for fetching variants in the user's workspace. ## February 3, 2025 ### API The [fetch component text](https://developer.dittowords.com/legacy/api-reference-legacy/components/fetch-component-text) (`GET /v1/components`) API endpoint now supports the `includeTimeData` query parameter. When `includeTimeData` is set to `true`, the response will include the `createdAt` and `updatedAt` fields for each component. This feature is only available when the `structured` format is used. ## November 11, 2024 ### Ditto React - 1.6.3 * Dependency upgrades See full release notes [here](https://github.com/dittowords/ditto-react/releases/tag/v1.6.3) ## May 21, 2024 ### Ditto CLI - 4.5.2 * Fix to include header distinguishing Ditto CLI requests from direct API requests. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v4.5.2). ## May 7, 2024 ### Ditto CLI - 4.5.1 * Fix issue with error logs not being flushed before exiting the CLI See full release notes [here](https://github.com/dittowords/cli/releases/tag/v4.5.1). ## May 3, 2024 ### Ditto Github Action - 0.3.0 * add optional name input parameter pr-title-prefix to distinguish prs with multi config setups See full release notes [here](https://github.com/dittowords/cli/releases/tag/v0.3.0). ## May 2, 2024 ### API / Web App Pluralization is now supported for all JSON formats when importing components via the Ditto web app or the [Fetch component text](https://developer.dittowords.com/legacy/api-reference-legacy/components/fetch-component-text) API endpoint. Example import data: ```json theme={null} { "fruit": "You have fruit in your cart.", "fruit_one": "You have one fruit in your cart.", "fruit_other": "You have some fruit in your cart." } ``` ## April 16, 2024 ### CLI v4.5.0 released to add support for a new option which disables the generation of `index.js` and `index.d.ts` files when working with JSON formats. See the release notes [here](https://github.com/dittowords/cli/releases/tag/v4.5.0). ## March 22, 2024 ### CLI v4.4.1 released to fix periodic hanging from attempting to exit the CLI process using Ctrl + C. See full release notes [here](https://github.com/dittowords/cli/releases/tag/v4.4.1). ## March 15, 2024 ### Documentation * Small fixes and wording clarifications on the [SDKs](/legacy/legacy-tools) page ## March 13, 2024 ### Ditto React - 1.6.1 * Fix crash when rich text is enabled See release notes: [https://github.com/dittowords/ditto-react/releases/tag/v1.6.1](https://github.com/dittowords/ditto-react/releases/tag/v1.6.1) ## February 29, 2024 ### Ditto CLI - 4.4.0 * Add `pull` --sample-data flag for variants See release notes: [https://github.com/dittowords/cli/releases/tag/v4.4.0](https://github.com/dittowords/cli/releases/tag/v4.4.0) ## February 27, 2024 ### Ditto API * `/v1/variants` now supports the `showSampleData` query parameter * Fix `/v1/variants` for `projectIds` query parameter ## February 19, 2024 ### Ditto CLI - 4.3.0 * `nested` format is now supported See release notes: [https://github.com/dittowords/cli/releases/tag/v4.3.0](https://github.com/dittowords/cli/releases/tag/v4.3.0) ### Ditto CLI - 4.2.3 * Upgrades to several dependencies See release notes: [https://github.com/dittowords/cli/releases/tag/v4.2.3](https://github.com/dittowords/cli/releases/tag/v4.2.3) ## January 22, 2024 ### Ditto CLI - 4.2.2 * Stop component folders with emojis from creating a leading separator See release notes: [https://github.com/dittowords/cli/releases/tag/v4.2.2](https://github.com/dittowords/cli/releases/tag/v4.2.2) ## December 12, 2023 ### Ditto API The `/components/file` [endpoint](https://developer.dittowords.com/legacy/api-reference-legacy/components/import-components-via-a-file) now supports a `folderId` query parameter. You can supply the Developer ID of one of your component folders, and all the components will be imported to that folder. ## December 7, 2023 ### Ditto React v1.3.2 released to fix a bug that incorrectly tracked the "Searching" location. ## November 28, 2023 ### Ditto CLI - 4.2.1 * Only run init() on commands that need it in [https://github.com/dittowords/cli/pull/89](https://github.com/dittowords/cli/pull/89) This change prevents the `ditto` directory from being created on commands that don't need it (e.g. `generate-suggestions`) See release notes: [https://github.com/dittowords/cli/releases/tag/v4.2.1](https://github.com/dittowords/cli/releases/tag/v4.2.1) ## November 16, 2023 ### Ditto CLI - 4.2.0 Add `--sample-data` flag to the `components-folders` command in [https://github.com/dittowords/cli/pull/88](https://github.com/dittowords/cli/pull/88) See release notes: [https://github.com/dittowords/cli/releases/tag/v4.2.0](https://github.com/dittowords/cli/releases/tag/v4.2.0) ## November 2, 2023 ### Ditto React Ditto text items with rich text can now be rendered natively by passing the `richText` property on either `Ditto` or `DittoText`. This expands rich text support from v1.5.0 which introduced support for rich text on components. Example: ```jsx theme={null} ``` ## October 30, 2023 ### Ditto CLI — 4.1.0 This release includes features designed to tighten integration for a variety of environments, including iOS, TypeScript, and more. See the release notes [here](https://github.com/dittowords/cli/releases/tag/v4.1.0). ### New example apps We've released new versions of our example applications, which have been updated to include the latest in recommended practices for integrating Ditto into development. See the full list [here](/example-apps#repositories). ## September 29, 2023 [Ditto Webhooks](/additional-tools/webhooks) have been released! ## August 29, 2023 ### Ditto React * Ditto components with rich text can now be rendered natively by passing the richText property on either Ditto or DittoComponent. * Example: `` ## August 18, 2023 ### Ditto API * Endpoints for fetching project text now support an `exclude_components` query parameter. * When `exclude_components=true`, only text items not associated with Ditto components will be returned from a given endpoint. ### Ditto CLI * We've released a new major version (v4) of the CLI. See the release notes [here](https://github.com/dittowords/cli/releases/tag/v4.0.0). ## August 15, 2023 ### Ditto API The behavior of variables when exporting to mobile formats (`.strings`, `.stringsdict`, and `.xml`) has changed. Variables will now maintain a consistent ordering across base text, variant text, and plural forms; they're assigned an index according to the order of usage (starting with base text, and then variants), and that index is maintained through variant exports. For example, consider the following text: ```json theme={null} // Base Text {{username}}, your role is {{role}}. // Variant Text Tú papel es {{role}}, {{username}}. Previously, exports for the base text and variant text would cause format specifier indices to be reversed for the variables: /* base-example.strings */ "text" = "%1$@, your role is %2$@."; /* spanish-example.strings */ "text" = "Tú papel es %1$@, %2$@."; To facilitate ease of integration into development, exports for variant text will now ensure that the format specifier indices match those in the base text: /* base-example.strings */ "text" = "%1$@, your role is %2$@."; /* spanish-example.strings */ "text" = "Tú papel es %2$@, %1$@."; ``` ## August 7, 2023 ### Ditto API * Support has been added for an `exclude_components` query parameter to the endpoint. * When set to `true`, only text items not associated with components will be returned from the endpoint. ### Ditto CLI * Small bug fix to ensure files aren't written to disk for empty API responses. * For more information, please refer to the release [here](https://github.com/dittowords/cli/releases/tag/v3.10.1). ## July 26, 2023 ### Ditto API * When exporting data for variants, variant metadata (name and description) is now included. * In the JSON formats, two new meta keys are added at the top level: `variant_name` and `variant-description` * In the Android `.xml`, iOS `.strings`, and iOS `.stringsdict` formats, a comment is added for each field at the top of the file ## July 17, 2023 ### Ditto API * The `flat` format now supports rich text. ## June 27, 2023 ### Ditto CLI * Added support for specifying a list of formats in the format configuration property. * For more information, please refer to the release [here](https://github.com/dittowords/cli/releases). ## June 26, 2023 ### Ditto React * `v1.4.1` fixes a bug introduced in `v1.4.0` which caused variables to ignore passed values. ## June 14, 2023 ### Ditto CLI * Added the `import-components` command which enables component imports via a file through the CLI. For information about the command please refer to the [documentation](https://github.com/dittowords/cli#import-components) in the README. ## June 12, 2023 ### Ditto API * We've added the new `POST /components/file` endpoint to enable uploading components through the API. ## June 8, 2023 ### VSCode Extension * Add the ability to only match on components from a component folder. Must be used with `v3.8.0` of the Ditto CLI. ### Ditto CLI * Add `component-folders` command which lists component folders in your workspace. See the release [here](https://github.com/dittowords/cli/releases/tag/v3.8.0). ## June 5, 2023 ### Ditto CLI * Add the `-cf` (`--component-folder`) flag for `generate-suggestions`. See the release [here](https://github.com/dittowords/cli/releases/tag/v3.7.0). ## June 2, 2023 ### Ditto CLI * Performance improvements. See the release [here](https://github.com/dittowords/cli/releases/tag/v3.6.1). ## May 30, 2023 ### Ditto CLI * We've added support for specifying the new `ios-stringsdict` format in the CLI configuration. See the release [here](https://github.com/dittowords/cli/releases/tag/v3.6.0). ### Ditto API We clarified a small point of confusion with the documentation around the request payload expected for the endpoint. The JSON payload should include a top-level data property: ```json theme={null} { "data": { "[API ID]": { "text": "[TEXT OF TEXT ITEM (CAN INCLUDE VARIABLES)]", "notes": "[NOTES OF TEXT ITEM]", // optional "tags": [ ... ], // optional: array of strings "plurals": [ // optional: array of plural objects { "text": "[TEXT OF PLURAL FORM]", "form": "[one|two|zero|few|many|other]" } ] } } } ``` ## May 12, 2023 ### Ditto API We've added support for the iOS `.stringsdict` format to our API. Read more [here](https://developer.dittowords.com/legacy/api-reference-legacy/text-formats#ios-.stringsdict-format-ios-stringsdict). ## May 3, 2023 ### Ditto CLI * Adds ICU support * Fixes a bug where pulling would fail on new initializations * [Full Changelog](https://github.com/dittowords/cli/compare/v3.3.0...v3.5.0) ## May 1, 2023 ### VS Code Extension We've create a VS Code extension! Check it out [here](https://marketplace.visualstudio.com/items?itemName=dittotech.vscode-ditto). ## April 28, 2023 ### Ditto API We've added support for an ICU JSON export format to our API. Read more [here](https://developer.dittowords.com/api-reference/text-formats#icu-json-format-icu). ## April 26, 2023 ### Ditto CLI `v3.4.0` of the CLI has been published, which adds a `-v`, `--version` flag to output what version of the CLI is being run. ## March 23, 2023 ### Ditto React We've published `v1.4.0`, which includes explicit support for map and list variables, in addition to miscellaneous cleanup. Read about the release [here](https://github.com/dittowords/ditto-react/releases/tag/v1.4.0). ## March 22, 2023 ### Ditto API, Ditto CLI, Ditto React We've added a `__type` property to variable output in our structured export format; this enables simple discrimination between different types of variables: ```json theme={null} { "some-variable-1": { "example": "Hello world!", "__type": "string" }, "some-variable-2": { "example": 100, "__type": "number" }, "some-variable-3": { "text:" "Foo", "url": "https://bar.com", "__type": "hyperlink" } } ``` ## March 21, 2023 ### Ditto API We've added support for a `nested` JSON export format to our API. Read more [here](https://developer.dittowords.com/api-reference/text-formats#nested-json-format-nested). ## March 9, 2023 ### Ditto CLI We've published `v3.0.0` of the CLI, which focuses around a number breaking changes intended to better align default CLI behavior with Ditto best practices. Read the release notes [here](https://github.com/dittowords/cli/releases/tag/v3.0.0). ## February 15, 2023 ### Ditto API We've released two bug fixes specific to the Android XML export format: * index values for format specifiers will now be relative to a text item's base value AND its plurals, instead of resetting for each plural form ([issue](https://github.com/dittowords/cli/issues/48)) * extra whitespace is no longer added between text and variables in the final output ([issue](https://github.com/dittowords/cli/issues/49)) ## February 14, 2023 ### Ditto API We've released a new version of our API that includes some breaking changes. The old API endpoints are deprecated, and existing users should migrate to the new endpoints at their earliest convenience. ## February 6, 2023 ### Ditto Web App * Removed the deprecated the full format from the export modals on the project page and in the component library * Set the flat format to be the default export format in the web app ## February 3, 2023 ### Ditto API Minor documentation update to add and emphasize a deprecation notice for the full format. ## February 1, 2023 ### Ditto React — 1.3.0 Added support for using variables in conjunction with the flat format. See the release [here](https://github.com/dittowords/ditto-react/releases/tag/v1.3.0). ## January 25, 2023 We added support to the web app for importing components from two new file formats: * Android localization files (.xml) * iOS localization files (.strings) Read more [here](https://dittov3.notion.site/Importing-JSON-iOS-Android-Files-256cc8865c7a80fe94cdf135631bf8c6). ## January 19, 2023 ### Ditto React — 1.2.1 * Updated README to clarify that the flat format does not currently support variables. * Fixed a bug preventing falsy values (namely 0 and "") from being properly interpolated. See the release [here](https://github.com/dittowords/ditto-react/releases/tag/v1.2.1). ## December 15, 2022 ### Ditto CLI Added rich text support. See more info [here](https://github.com/dittowords/cli#richtext) ## December 13, 2022 ### Ditto API Added the `includeRichText` flag to the following endpoints (format must be full or structured): * `/projects` * `/projects/:id` * `/projects/:id/components` * `/components` * `/component-folders/:api*id/components` ## November 30, 2022 ### Ditto CLI Added the `status` filter as a configuration variable. To filter the fetched text by its status, you can now use the `status` parameter in your `config.yml`. ## November 29, 2022 ### Ditto CLI Added `android` and `ios-strings` as available formats. To use these formats, specify them under the format paramter in your `config.yml`. ## November 10, 2022 ### Ditto API Fixed a typo in an example in the documentation containing an incorrect usage of the curl command. ### Ditto CLI Added information to the README about two supported environment variables: * `DITTO_CONFIG_FILE:` used to specify an alternate file location for the CLI to read authentication information from. The default path is `$HOME/.config/ditto`. * `DITTO_TEXT_DIR`: used to specify an alternate folder location for the CLI to write its output files to. The default path is `./ditto`. ## Oct 11, 2022 ### Ditto API * Added new endpoint: Fetch component folders * Added new endpoint: Fetch components by component folder * Added sub-headings to divide the endpoints by the entity they're associated with, and implemented minor miscellaneous cleanup across the endpoint documentation ## Sep 23, 2022 ### Ditto API Text items with plural values will have those plural values included in flat exports as individual key/value pairs; pluralized keys are structured like `[TEXT ID]_[PLURAL FORM]`. See the [flat format documentation](/string-formats/json#flat-json) for more details. Fixed a bug where the status field failed to properly filter returned data when specified in conjunction with the `android` or `ios-strings` formats. ## Sep 19, 2022 ### Ditto React — 1.2.0 * We exported two hooks that can be used for accessing synced data: `useDittoSingleText` and `useDittoComponent`. These hooks are experimental and will likely undergo API changes in the future. * See the release [here](https://github.com/dittowords/ditto-react/releases/tag/v1.2.0). ### Ditto API * Added the `status` field to data returned from the `/components` and `/projects/:id/components` endpoints. ## Jun 30, 2022 ### Ditto API * Added support for including variables in payloads sent to the `PUT /components` endpoint. * Fixed an issue with Android & iOS export formats not escaping special characters: `\n`, `\t`, `@`, `?`, `'`, and `"` characters are now properly escaped. * Added missing `xliff` namespace to exported Android `.xml` files. \= Fixed a bug with Android `.xml` exports that occurred with text items with API IDs that include the `-` character. Now, all `-` characters are replaced with `\_` characters in the name property of `` and `` tags, and a `ditto_api_id` property has been added to string and plural tags to serve as a reference to the original API ID. ### Ditto CLI — 2.5.1 * Fixed a bug when using the `project add` / `project remove` commands and selecting the component library caused incorrect modifications to be made to the CLI's configuration file. * See the release [here](https://github.com/dittowords/cli/releases/tag/v2.5.1). ### Ditto Example Projects * Added new iOS Example Project showcasing how to use exported .strings files. * Added new Android Example Project showcasing how to use exported .xml string files. See [Example Projects](/example-apps) for more details. ## Jun 13, 2022 ### Ditto GitHub Action — 0.2.0 Added an optional `ditto-dir` input parameter for projects that do not have the ditto directory in the root of the repository ## June 7, 2022 ### Ditto API Added support for upserting plurals via the `PUT /components`. See our [API documentation](/api-reference/authentication) for more details. ## June 1, 2022 ### Ditto API * Added early support for exporting text data to Android and iOS Strings formats. All endpoints that support a `format` query parameter can now accept values of `android` or `ios-strings`. * Added `GET /variables` endpoint that returns the variables in the workspace of the requesting user. * Added the ability to filter by text item status by passing a status query parameter in API requests. Supported by the following endpoints: * `GET /projects` * `GET /projects/:id` * `GET /projects/:id/components` * `GET /components` See our [API documentation](/api-reference/authentication) for more details. ## May 23, 2022 ### Ditto CLI — 2.5.0 * Added meta option flag in support of the Ditto GitHub Action release. See the release [here](https://github.com/dittowords/cli/releases/tag/v2.5.0). ### Ditto GitHub Action — 0.1.0 * v0.1.0 released! Check it out [here](https://github.com/dittowords/ditto-github-action). ## May 16, 2022 ### Ditto CLI — 2.4.0 * Update some user-facing CLI messages to accurately reflect our new subdomain: app.dittowords.com (instead of the old beta.dittowords.com). See the release [here](https://github.com/dittowords/cli/releases/tag/v2.4.0). ## May 10, 2022 ### Ditto CLI — 2.3.0 * Allows users to override the output directory via a new environment variable `DITTO_TEXT_DIR` * When no projects are found in the `config.yml` file an additional help message displays about verifying that the projects have developer mode enabled * See the release [here](https://github.com/dittowords/cli/releases/tag/v2.3.0). ## February 28, 2022 ### Ditto API Added better error handling for the niche edge case where an API request is made using the token of a user that has been removed from their workspace. ## January 20, 2022 ### Ditto React — 1.1.1 * Our React SDK now supports variable interpolation by passing in values through the variables prop. * Our React SDK now supports displaying plural forms through the count prop. For more information about using variable interpolations and pluralization through our React SDK, check out our [SDK documentation](/legacy/legacy-tools). ### Ditto CLI — 2.2.0 * The CLI now supports reading API keys from an environment variable (`DITTO_API_KEY`). * See the release [here](https://github.com/dittowords/cli/releases/tag/v2.2.0). ## January 11, 2022 ### Ditto CLI We deployed a bugfix release to fix issues introduced in the latest minor version of the package: * the pull command no longer crashes when projects other than the component library are specified in `config.yml` * resolves a casing issue in the project add command that was causing it to crash See the release [here](https://github.com/dittowords/cli/releases/v2.1.2). ## January 6, 2022 ### Ditto CLI We've added a new supported property to `ditto/config.yml` to allow explicitly specifying that the component library should be fetched and included in the CLI's output: `components: true` This is now the preferred alternative to the old way of specifying the component library: ```yml theme={null} projects: name: Ditto Component Library id: ditto_component_library ``` Our goal with this change is to make the CLI easier to use and understand by aligning it with the way things work in the Ditto web app, where the component library is fundamentally different from the projects in a workspace. See the release [here](https://github.com/dittowords/cli/releases/tag/v2.1.1). ## December 8, 2021 ### Ditto API * `GET /projects/:id/components` can now be used to fetch the components used in a project * Return format matches the `GET /components` endpoint * Supports `format` and `variant` parameters (the same as the `/projects`, `/project/:id`, and `/components` endpoints) ## November 29, 2021 ### Ditto API * `GET /components` can now be used to fetch the components in a workspace * Supports format and variant parameters (the same as the `/projects` and `/project/:id` endpoints) * `GET /projects/ditto_component_library` has been deprecated; the endpoint is still available, but references to it have been removed from the documentation. * `PUT /components` can now be used to update the text of components in a workspace * Currently only supports updating variant text via the variant query parameter (an error will be thrown if not specified) * Currently only available to teams on Team or Enterprise plans * Data is specified on data key in request body and must be in one of our [three supported import formats](https://dittov3.notion.site/Importing-JSON-iOS-Android-Files-256cc8865c7a80fe94cdf135631bf8c6) ## November 11, 2021 ### Ditto CLI — 2.0.0 * Output files are now written to disk in several different ways according to how the CLI is configured; most notably, if the variants option is set and a format of structured or flat is specified, output files will be written on a per-project per-variant basis * Data for `structured` and `flat` formats is saved without arbitrary top-level nesting * Files are only written for variants that contain values for the configured projects (no more empty files) For a more in-depth description (with examples) of these changes and others in the release, see the full release notes [here](https://github.com/dittowords/cli/releases/tag/v2.0.0). ### Ditto React — 1.0.0 * `ditto-react` now only works with CLI version `2.x.x` — leaning into new CLI improvements allowed us to drastically reduce many areas of complex logical overhead * We made some stabilization improvements to the way that missing/invalid `frameId`, `blockId`, `textId`, or `componentId` values are handled * We implemented significant refactoring in several areas of the project For a more in-depth description of these changes, see the full release notes [here](https://github.com/dittowords/ditto-react/releases/tag/v1.0.0) ### Ditto Demo * We added a [new branch](https://github.com/dittowords/ditto-demo/tree/react-i18next) that showcases how Ditto can be integrated into a project with react-i18next * We updated dependencies to the latest versions of the Ditto CLI (v2.0.0) and Ditto React (v1.0.0) ## October 22, 2021 ### Ditto API — 2.4.1 * We fixed a bug with the API (and in-app exports) that included hidden text in `flat` and `structured` JSON exports. Now, hidden text will correctly not be included in these export formats! ### Ditto Demo * We included the files to import into the component library separately from where they'd be synced via the CLI * We included more instructions on linking the demo app with its corresponding design file ## October 7, 2021 ### General * Refactored API documentation to be easier to navigate and communicate critical concepts more clearly ### Ditto CLI — 1.1.1 * When the `pull` command is executed, all `.json` and `.js` files are now removed from the `ditto` folder prior to new data being written \= Support added for new options in `ditto/config.yml`: * `variants`: `true` or `false` * If set to true, data will be fetched for both base and variant text and stored in separate JSON files * `format`: `flat` or `structured` - If specified, data will be fetched and stored in the specified format \= Refactored `README` * `GET /variants` will now return names and API IDs for variants in the workspace associated with the requesting user. ### Ditto React — 0.0.5 * Support added for `flat` and structured formats * Support added for passing a `variant` value to `DittoProvider` * Bug fixes around support for integrating with workspace component libraries (as opposed to individual projects) * Refactored `README` ### Ditto Demo * Refactored `ditto-sdk` usage to integrate with a component library instead of an individual project * Added a language picker to showcase `ditto-react` and `ditto-cli` support for variants * Refactored `README`, including adding instructions for connecting the repo to a component library ## September 27, 2021 ### General Fixed incorrect example of `/projects` usage in API Reference. The `projectIds` query parameter should be specified as follows: * Correct: `?projectIds[]=&projectIds[]=` * Incorrect: `?projectIds[]=,` ### API — 2.4.0 `GET /variants` will now return names and API IDs for variants in the workspace associated with the requesting user. ## September 8, 2021 ### API — 2.3.0 * `GET /projects` and `GET /projects/:id` now accept an optional query parameter of `variant`; when provided, the data exported will be specific to the variant with an API ID that matches the parameter's value. For `default` and `structured` formats, the variants key will not be included when the variant parameter is provided. Example: `/projects/?variant=xxx-xxx-xxx` * `GET /projects/:id` will not include top-level projects and project\_xyz keys Example request: `GET /projects/123` Example response before change: ```json theme={null} { projects: { project_123: { text_item: "Hello World", ... }}} ``` Example response after change: ```json theme={null} { text_item: "Hello World", ... } ``` ## August 11, 2021 ### API — 2.2.0 `GET /projects` and `GET /projects/:id` now accepts an optional query parameter of `format`, which can be either `flat` or `structured`. If no format is provided, the `full` JSON of the project will be returned with blocks and frames. Example: `/projects/?format=flat` ## July 28, 2021 With the recent release of [Variants for Components](https://dittov3.notion.site/Variants-for-Components-256cc8865c7a80bb8c44da73209fb0cc), we've included them in both exports from our web-app and the JSON response from the API. ### API — 2.1.0 * `GET /projects/:id` will now return component variants. This applies both for when fetching projects or when fetching the component library (i.e. id = ditto\_component\_library) * `GET /projects/:id` will now match the project JSON export from the web-app to include component information (`is_comp` and `component_api_id`) in the text object ## June 21, 2021 We've updated our React library and our demo project to work with the multi-project JSON structure that the CLI now saves in `text.json`. ### Ditto React — 0.0.4 TypeScript bindings are now exported 🎉 A new `projectId` prop can be passed to `DittoProvider` or `Ditto` * If passed to `DittoProvider`, all descendant `Ditto` components will default to pulling text from the associated project * If passed to `Ditto`, the component will pull text from the associated project * If passed to both `DittoProvider` and `Ditto`, the value passed to `Ditto` will take precedence * Breaking change: If a `Ditto` component is rendered that is not provided a `projectId` via direct prop or `DittoContext` ancestor, an error will be thrown See more details in the [updated documentation](https://www.npmjs.com/package/ditto-react). ### Ditto Demo * Upgraded `ditto-react` to `v0.0.4` * Updated source to work with new `ditto-react` version by passing `projectId` props to all instances of `DittoContext` ## June 7, 2021 We've updated both our CLI and API to handle multiple projects. Heads up! This results in some breaking changes to the CLI in order for it to list projects, and will change the format of the `text.json` fetched by the CLI. Please upgrade your Ditto CLI via either `npm` or `yarn`. ### API — 2.0.0 * `GET /project-names` is the new name of the previous `GET /projects` endpoint. Just as before, this will return the names and IDs of projects in your Ditto workspace with Developer Mode turned on * `GET /projects/:id` will now return the structured JSON in a format compatible with multiple projects * `GET /projects` is a new endpoint that will return the content of multiple projects (specified via the query parameter projectIds) as a single JSON object ### CLI — 1.0.0 * We've updated the CLI to handle syncing multiple projects in a single directory! This means several things: `/ditto/config.yml` now supports multiple projects. `ditto-cli` pull will pull all projects in the current directory's /`ditto/config.yml` * We've added two new commands to add and remove projects from `/ditto/config.yml` * `ditto-cli project add` * `ditto-cli project remove` * The regular `ditto-cli project` command will now function as `ditto-cli project add` ## April 1, 2021 ### API — 1.1.0 * `GET /projects` now includes the Component Library if Developer Mode is enabled for the Component Library * `GET /projects/:id` will return the Component Library as a structured JSON if the ID provided is `ditto_component_library` ## February 25, 2021 ### API — 1.0.0 * `GET /projects` endpoint for fetching Ditto projects from workspace * `GET /projects/:id` endpoint for fetching content in Ditto project as structured JSON This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.