### Retrieve All Styleguides

Source: https://developer.dittowords.com/api-reference/styleguides/get-styleguides

This example shows how to make a GET request to the /styleguides endpoint to retrieve all styleguides. Ensure you have the necessary authentication headers.

```shell
curl --request GET \
  --url https://api.dittowords.com/v1/styleguides \
  --header "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Get style guides

Source: https://developer.dittowords.com/api-reference/styleguides/get-styleguides

Returns the style guides created in the workspace, with their sections and rules. The built-in default style guide is not included.

```APIDOC
## GET /styleguides

### Description
Returns the style guides created in the workspace, with their sections and rules. The built-in default style guide is not included.

### Method
GET

### Endpoint
/styleguides

### Parameters
#### Query Parameters
- **developerIds** (string) - Optional - Comma-separated list of style guide developer IDs to return.

### Response
#### Success Response (200)
- **styleguides** (array) - The workspace-created style guides.
  - **developerId** (string) - The style guide's developer ID.
  - **name** (string) - The style guide's name.
  - **description** (string) - The style guide's description.
  - **variant** (object) - The variant/locale this guide is scoped to, or null for a base guide.
    - **id** (string) - The variant's developer ID.
    - **name** (string) - The variant's name.
    - **localeCode** (string) - BCP-47 locale code, or null.
  - **sections** (array) - 
    - **sectionId** (string) - The section's ID, used to attach rules to this section.
    - **name** (string) - The section's name.
    - **kind** (string) - Enum: rules
    - **rules** (array) - 
      - **name** (string) - The rule's name.
      - **description** (string) - What the rule enforces.
      - **examples** (array) - 
        - **from** (string) - Text that violates the rule.
        - **to** (string) - Text that conforms to the rule.
```

--------------------------------

### Scaffold DialogueModal Component Example

Source: https://developer.dittowords.com/ditto-specs-cli-reference/commands

Example of scaffolding a specific component, DialogueModal, into a designated directory.

```bash
npx ditto-spec scaffold DialogueModal --path src/components/DialogueModal
```

--------------------------------

### Complex Configuration Example

Source: https://developer.dittowords.com/cli-reference/configuration

This example demonstrates a comprehensive configuration with multiple outputs, specifying different formats, frameworks, variants, and output directories.

```yaml
projects:
  - id: my-project
components:
  folders:
    - id: root
      excludeNestedFolders: true
variants: []
richText: html
outDir: ./ditto/top
outputs:
  - format: json
  - format: json
    framework: vue-i18n
    variants:
      - id: french
    outDir: ./ditto/french
  - format: json
    framework: i18next
    outDir: ./ditto/i18next
    type: module
    projects: []
    components:
      - id: special-folder
    variants:
      - id: french
      - id: spanish
      - id: base
    richText: false
```

--------------------------------

### Install Ditto CLI with npm

Source: https://developer.dittowords.com/cli-reference/authentication

Install the Ditto CLI as a development dependency using npm.

```bash
npm i --save-dev @dittowords/cli
```

--------------------------------

### Example API Request with cURL

Source: https://developer.dittowords.com/api-reference/authentication

Use cURL to make a GET request to the /projects endpoint, including your API key in the Authorization header.

```sh
curl -X GET \
 --header "Authorization: <YOUR_API_KEY>" \
 "https://api.dittowords.com/v2/projects"
```

--------------------------------

### Install Ditto CLI with Yarn

Source: https://developer.dittowords.com/cli-reference/authentication

Install the Ditto CLI as a development dependency using Yarn.

```bash
yarn add --dev @dittowords/cli
```

--------------------------------

### iOS .strings Format Example

Source: https://developer.dittowords.com/string-formats/ios

Basic example of key-value pairs in the .strings format. Used for simple text localization.

```swift
"welcome.title" = "Welcome, %1$@!";

/* This should only be used on the logout screen */
"logout" = "Logout";
```

--------------------------------

### Display Ditto CLI Help

Source: https://developer.dittowords.com/cli-reference/authentication

Run the help command to see a list of available commands after installation.

```bash
npx @dittowords/cli --help
```

--------------------------------

### Print All Platform Style Guide Rules

Source: https://developer.dittowords.com/ditto-specs-cli-reference/commands

Use the `rules` command to print every style guide rule on the Ditto platform, grouped by style guide and section. It shows the kind (`rules` or `wordlist`) and section ID for each rule. Requires `DITTO_API_KEY`.

```bash
npx ditto-spec rules
```

--------------------------------

### create_styleguide_rule

Source: https://developer.dittowords.com/mcp-reference/tools

Create a new rule in a style guide (name, description, examples, tags).

```APIDOC
## create_styleguide_rule

### Description
Create a new rule in a style guide (name, description, examples, tags).

### Method
POST

### Endpoint
/styleguide/rules

### Request Body
- **name** (string) - Required - The name of the rule.
- **description** (string) - Required - The description of the rule.
- **examples** (array) - Optional - A list of example strings.
- **tags** (array) - Optional - A list of tags associated with the rule.
```

--------------------------------

### Install Ditto Specs CLI with npm

Source: https://developer.dittowords.com/ditto-specs-cli-reference/setup

Install the Ditto Specs CLI as a development dependency using npm.

```bash
npm i --save-dev @dittowords/spec-cli
```

--------------------------------

### Filter Platform Style Guide Rules by Style Guide

Source: https://developer.dittowords.com/ditto-specs-cli-reference/commands

Use the `--styleguide` flag with the `rules` command to limit the output to a specific style guide. This is useful for inspecting rules within a particular style guide.

```bash
npx ditto-spec rules --styleguide "<name-or-id>"
```

--------------------------------

### Create Style Guide Rule from Code Review Comment

Source: https://developer.dittowords.com/mcp-reference/examples

Turn recurring content issues identified in code reviews into actionable Ditto style guide rules. This example prompt instructs the agent to create a rule for neutral, solution-oriented error messages.

```text
We keep shipping error messages that blame the user. Add a Ditto style
guide rule that error messages should be neutral and solution-oriented,
with an example like "You entered an invalid email" → "Enter a valid
email address."
```

--------------------------------

### Install Ditto Specs CLI with yarn

Source: https://developer.dittowords.com/ditto-specs-cli-reference/setup

Install the Ditto Specs CLI as a development dependency using yarn.

```bash
yarn add --dev @dittowords/spec-cli
```

--------------------------------

### Display Ditto CLI Help

Source: https://developer.dittowords.com/cli-reference

Run the help command to see a list of available commands after installation. This command requires npx, which is included with npm 5.2+.

```bash
npx @dittowords/cli --help

```

--------------------------------

### CLI Configuration: Variants

Source: https://developer.dittowords.com/cli-reference/configuration

Examples demonstrating how to configure which variants to return. This includes returning base text only, base text and all variants, or specific variants like French and Spanish.

```yaml
# Returns base text only
variants: []
```

```yaml
# Returns base text and all variants
variants:
  - id: all
```

```yaml
# Returns french and spanish variant text
variants:
  - id: french
  - id: spanish
```

```yaml
# Returns base text, french and spanish variants
variants:
  - id: base
  - id: french
  - id: spanish
```

--------------------------------

### Find Style Guide Rule Gaps

Source: https://developer.dittowords.com/ditto-specs-cli-reference/agent-skills

Use this command to find style guide rule gaps by analyzing component copy. Omit the argument to analyze all components with Ditto specs.

```bash
/ditto-spec-gaps <ComponentName or path>
```

--------------------------------

### Combine Style Guide and Text Reuse Tools

Source: https://developer.dittowords.com/mcp-reference/examples

Combine instructions for both style guide compliance and text reuse for optimal results. This ensures all new UI text adheres to content guidelines and prioritizes reusing existing Ditto text.

```text
When working on UI:
- Use the style guides in Ditto to ensure all user-facing text follows
  our content guidelines.
- Try to reuse existing text from Ditto instead of writing new copy.
```

--------------------------------

### Get All Variables

Source: https://developer.dittowords.com/api-reference/variables/get-variables

Fetches all variables defined for the project. This includes details like the variable's name, type, example data, and fallback values.

```APIDOC
## GET /websites/developer_dittowords/variables

### Description
Retrieves a list of all variables defined for the project. Each variable object contains its ID, name, type, and associated data, which may include examples and fallback values.

### Method
GET

### Endpoint
/websites/developer_dittowords/variables

### Parameters
This endpoint does not accept any path or query parameters.

### Request Body
This endpoint does not accept a request body.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the variable.
- **name** (string) - The display name of the variable.
- **type** (string) - The data type of the variable (e.g., "string", "number", "list", "map", "hyperlink").
- **data** (object) - An object containing variable-specific data, such as example values, fallback values, text, or URLs.

### Response Example
```json
[
  {
    "id": "Age",
    "name": "Age",
    "type": "number",
    "data": {
      "example": 21,
      "fallback": "18"
    }
  },
  {
    "id": "Jobs",
    "name": "Jobs",
    "type": "string",
    "data": {
      "example": "Engineer",
      "fallback": "Designer"
    }
  },
  {
    "id": "Link",
    "name": "Link",
    "type": "hyperlink",
    "data": {
      "text": "View",
      "url": "https://www.google.com/"
    }
  },
  {
    "id": "List",
    "name": "List",
    "type": "list",
    "data": [
      "true",
      "false"
    ]
  },
  {
    "id": "Map",
    "name": "Map",
    "type": "map",
    "data": {
      "0": "Zero",
      "1": "One",
      "2": "Two"
    }
  }
]
```
```

--------------------------------

### CLI Configuration: Fetching Specific Component Folders

Source: https://developer.dittowords.com/cli-reference/configuration

Example of how to specify component folders to pull text from. This configuration fetches top-level components and all components within 'folder-1', including nested ones.

```yaml
components:
  folders:
    - id: root
      excludeNestedFolders: true
    - id: folder-1
```

--------------------------------

### Fetching a Specific Project

Source: https://developer.dittowords.com/feedback-support/changelog

Example request for retrieving a specific project by its ID.

```HTTP
GET /projects/123
```

--------------------------------

### Workspace Spec Example

Source: https://developer.dittowords.com/ditto-specs-cli-reference/spec-files

This is an example of a workspace spec file. It defines universal rules and available tags. The 'workspace: true' key marks it as the workspace spec.

```yaml
---
workspace: true
# Managed by Ditto — do not edit below
tags: [body, button, call-to-action, dialog-title, heading, nav]
rules:
  - name: Write in active voice
    description: Lead with verbs, avoid passive constructions
    section: Voice & Tone
locales:
  de-DE:
    - name: Use informal address
      description: Use "Du" instead of "Sie" for all user-facing copy
      section: Formality
---
```

--------------------------------

### Generated Output File Structure

Source: https://developer.dittowords.com/cli-reference/configuration

Illustrates the directory structure and file names generated based on the complex configuration example, showing how different outputs map to specific files.

```shell
. 
└── ditto/ 
    └── top/ 
        ├── my_project__base.json 
        └── components__base.json 
    └── french/ 
        ├── my_project__french.json 
        ├── components__french.json 
        ├── variables.json 
        └── index.js 
    └── i18next/ 
        ├── my_project__french.json 
        ├── my_project__base.json 
        ├── my_project__french.json 
        ├── my_project__spanish.json 
        ├── my_other_project__base.json 
        ├── my_other_project__french.json 
        ├── my_other_project__spanish.json 
        ├── components__base.json 
        ├── components__french.json 
        ├── components__spanish.json 
        ├── variables.json 
        └── index.js
```

--------------------------------

### Initialize Agent Skills

Source: https://developer.dittowords.com/ditto-specs-cli-reference/agent-skills

Installs three slash commands into `.claude/commands/` for interactive agent workflows. These commands are committed to your repository.

```bash
/ditto-spec init --agent
```

--------------------------------

### iOS .stringsdict Format Example

Source: https://developer.dittowords.com/string-formats/ios

Example of the .stringsdict format for handling plural forms in iOS applications. Includes variable definitions and plural rules.

```xml
<?xml version="1.0" encoding="utf-8"?>
<plist version="1.0">
    <dict>
        <!-- Variables: cartCount, username -->
        <key>cart.header</key>
        <dict>
            <key>NSStringLocalizedFormatKey</key>
            <string>%1$#@count@</string>
            <key>count</key>
            <dict>
                <key>NSStringFormatSpecTypeKey</key>
                <string>NSStringPluralRuleType</string>
                <key>NSStringFormatValueTypeKey</key>
                <string>d</string>
                <key>one</key>
                <string>%3$@, you have one item in the cart.</string>
                <key>two</key>
                <string>%3$@, you have a couple of items in the cart.</string>
                <key>other</key>
                <string>%3$@, you have %2$@ items in the cart.</string>
            </dict>
        </dict>
    </dict>
</plist>
```

--------------------------------

### Import JSON with Pluralization Support

Source: https://developer.dittowords.com/feedback-support/changelog

Example JSON data demonstrating pluralization support for importing components. Use different keys for singular, plural, and other forms.

```json
{
  "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."
}
```

--------------------------------

### CLI Configuration: Fetching Specific Projects

Source: https://developer.dittowords.com/cli-reference/configuration

Example of how to specify which projects to pull text from using their Developer IDs. This configuration will fetch all text from 'project-1' and 'project-2'.

```yaml
projects:
  - id: project-1
  - id: project-2
```

--------------------------------

### OpenAPI Component Definition Example

Source: https://developer.dittowords.com/api-reference/components/create-components

An example of an OpenAPI component definition including name, variables, plurals, and localized variants.

```yaml
name: Cart Count
variables:
  - count
plurals:
  - form: one
    text: '{{count}} item in your cart'
  - form: other
    text: '{{count}} items in your cart'
- text: Hello world
  name: Localized Component
  variants:
    - variantId: french
      text: Bonjour le monde
```

--------------------------------

### Sync Style Guide Rules with Ditto Specs

Source: https://developer.dittowords.com/ditto-specs-cli-reference/commands

Use the `pull` command to sync style guide rules from the Ditto platform into your local Ditto spec files. This command matches rules by tag intersection. Requires `DITTO_API_KEY`.

```bash
npx ditto-spec pull
```

--------------------------------

### Full dittospec.config.json with all options

Source: https://developer.dittowords.com/ditto-specs-cli-reference/setup

This configuration includes all available options for controlling spec file discovery and style guide syncing.

```json
{
  "apiBase": "https://api.dittowords.com",
  "workspaceId": "your-workspace-id",
  "roots": ["design-system", "src/components"],
  "styleguides": ["Brand Voice", "Product UI"],
  "locales": ["de-DE", "fr-FR"],
  "defaultStyleguide": "Brand Voice"
}
```

--------------------------------

### Create Rules with Stdin Input

Source: https://developer.dittowords.com/ditto-specs-cli-reference/commands

Provides a batch of style rules and terminology entries via standard input using a heredoc. This example includes both a style rule and a terminology entry.

```bash
npx ditto-spec create-rules <<'EOF'
[
  {
    "name": "Use active voice in CTAs",
    "description": "Lead CTAs with a verb",
    "tags": ["button", "call-to-action"],
    "examples": [{"from": "Your settings", "to": "Open settings"}],
    "section": "UI Patterns"
  },
  {
    "term": "sign up",
    "disallowed": ["signup", "sign-up"],
    "description": "Two words as a verb",
    "section": "Word List"
  }
]
EOF
```

--------------------------------

### get_styleguide_rules

Source: https://developer.dittowords.com/mcp-reference/tools

Fetches style guide rules from your Ditto workspace, including both workspace-level and project-specific rules. Use this to ensure AI-generated UI text follows your team's content guidelines.

```APIDOC
## get_styleguide_rules

### Description
Fetches style guide rules from your Ditto workspace, including both workspace-level and project-specific rules. Use this to ensure AI-generated UI text follows your team's content guidelines.

### Method
GET

### Endpoint
/styleguide/rules
```

--------------------------------

### Tagging in a Design System

Source: https://developer.dittowords.com/ditto-specs-cli-reference/spec-files

Illustrates how Ditto specs support component-level and surface-level tagging to organize and apply style guide rules within a design system.

```yaml
tags: [dialog, confirmation]        # rules about dialogs apply to ALL surfaces
surfaces:
  headline:
    tags: [heading, dialog-title]    # + rules about headings apply here
  actionText:
    tags: [call-to-action]           # + rules about CTAs apply here
  cancelText:
    tags: [button]                   # + rules about buttons apply here
```

--------------------------------

### Component Spec File Example

Source: https://developer.dittowords.com/ditto-specs-cli-reference/spec-files

Defines a DialogueModal component with tags, surfaces, and rules for content governance. Managed by Ditto, with specific sections for voice and tone, terminology, and locale-specific settings.

```yaml
---
component: DialogueModal
tags: [dialog, confirmation]
surfaces:
  headline:
    tags: [heading, dialog-title]
    maxLength: 60
  content:
    tags: [body, dialog-body]
    maxLength: 240
  actionText:
    tags: [call-to-action]
    maxLength: 25
  cancelText:
    tags: [button]
    maxLength: 25
# Managed by Ditto — do not edit below
rules:
  - name: Confirmation dialogs should be direct
    description: Keep confirmation copy terse and unambiguous
    section: Voice & Tone
  - surface: actionText
    name: Calls to action should use active voice
    description: Always lead with a verb
    examples:
      - from: "Your settings"
        to: "Open settings"
    section: Voice & Tone
  - term: sign up
    disallowed:
      - signup
      - sign-up
    description: Always use as two words (verb form)
    section: Terminology
locales:
  de-DE:
    - name: Use informal address
      description: Use "Du" instead of "Sie" for all user-facing copy
      section: Formality
---

```

--------------------------------

### Initialize Ditto Project

Source: https://developer.dittowords.com/ditto-specs-cli-reference/setup

Run the init command from your repository root to create the project configuration file and the workspace-level Ditto spec file.

```bash
npx ditto-spec init
```

--------------------------------

### Get Style Guides OpenAPI Specification

Source: https://developer.dittowords.com/api-reference/styleguides/get-styleguides

This OpenAPI specification defines the endpoint for retrieving style guides. It details the request parameters and the structure of the response, including style guide details, sections, and rules.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Ditto API
  description: Programmatically read and write data in your Ditto workspace.
servers:
  - url: https://api.dittowords.com/v2
security: []
paths:
  /styleguides:
    get:
      tags:
        - Style guides
      summary: Get style guides
      description: >-
        Returns the style guides created in the workspace, with their sections
        and rules. The built-in default style guide is not included.
      parameters:
        - schema:
            type: string
            description: Comma-separated list of style guide developer IDs to return.
          required: false
          description: Comma-separated list of style guide developer IDs to return.
          name: developerIds
          in: query
      responses:
        '200':
          description: The workspace-created style guides.
          content:
            application/json:
              schema:
                type: object
                properties:
                  styleguides:
                    type: array
                    items:
                      type: object
                      properties:
                        developerId:
                          type: string
                          description: The style guide's developer ID.
                        name:
                          type: string
                          description: The style guide's name.
                        description:
                          type: string
                          description: The style guide's description.
                        variant:
                          type: object
                          nullable: true
                          properties:
                            id:
                              type: string
                              description: The variant's developer ID.
                            name:
                              type: string
                              description: The variant's name.
                            localeCode:
                              type: string
                              nullable: true
                              description: BCP-47 locale code, or null.
                          required:
                            - id
                            - name
                            - localeCode
                          description: >-
                            The variant/locale this guide is scoped to, or null
                            for a base guide.
                        sections:
                          type: array
                          items:
                            oneOf:
                              - type: object
                                properties:
                                  sectionId:
                                    type: string
                                    description: >-
                                      The section's ID, used to attach rules to
                                      this section.
                                  name:
                                    type: string
                                    description: The section's name.
                                  kind:
                                    type: string
                                    enum:
                                      - rules
                                  rules:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        name:
                                          type: string
                                          description: The rule's name.
                                        description:
                                          type: string
                                          description: What the rule enforces.
                                        examples:
                                          type: array
                                          items:
                                            type: object
                                            properties:
                                              from:
                                                type: string
                                                description: Text that violates the rule.
                                              to:
                                                type: string

```

--------------------------------

### Remove Outdated Style Guide Rule

Source: https://developer.dittowords.com/mcp-reference/examples

Delete an outdated or no longer relevant style guide rule from Ditto. This example prompt instructs the agent to remove the 'title case headings' rule.

```text
We no longer use title case anywhere. Delete the "title case headings"
rule from our Ditto style guide.
```

--------------------------------

### Refine Existing Style Guide Rule

Source: https://developer.dittowords.com/mcp-reference/examples

Update an existing Ditto style guide rule to be more specific or comprehensive. This example prompt instructs the agent to modify the 'date formatting' rule to include relative times.

```text
Our "date formatting" rule in Ditto only covers full dates. Update it to
also specify that relative times like "2 hours ago" are lowercase.
```

--------------------------------

### Initialize Ditto Specs CLI for Agent Mode

Source: https://developer.dittowords.com/ditto-specs-cli-reference/setup

Run this command to set up the AI development tool configuration. It writes configuration for your AI development tool.

```bash
npx ditto-spec init --agent
```

--------------------------------

### OpenAPI Specification for Fetch Projects

Source: https://developer.dittowords.com/api-reference/projects/get-projects

This OpenAPI 3.0.0 specification defines the GET /projects endpoint, which returns a list of Ditto projects. It includes details on request parameters, response schemas, and example responses.

```yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Ditto API
  description: Programmatically read and write data in your Ditto workspace.
servers:
  - url: https://api.dittowords.com/v2
security: []
paths:
  /projects:
    get:
      tags:
        - Projects
      summary: Fetch projects
      description: Returns a list of Ditto projects in your workspace.
      responses:
        '200':
          description: Returns an array of projects in the workspace
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The Developer ID of the project
                    name:
                      type: string
                      description: The name of the project
                  required:
                    - id
                    - name
                example:
                  - id: my-first-project
                    name: My First Project
                  - id: my-second-project
                    name: My Second Project
                  - id: project-in-folder
                    name: Project in Folder
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

```

--------------------------------

### Create Rules with JSON File

Source: https://developer.dittowords.com/ditto-specs-cli-reference/commands

Creates rules using a JSON file and specifies a target style guide. The `--file` flag points to the JSON data, and `--styleguide` selects the destination.

```bash
npx ditto-spec create-rules --file rules.json --styleguide "Brand Voice"
```

--------------------------------

### vue-i18n Variable Interpolation Example

Source: https://developer.dittowords.com/cli-reference/files

This JSON example illustrates how vue-i18n handles string interpolation using single curly braces for variables, as shown in the 'welcome' and 'text-item-developer-id' fields.

```json
{
	"text-item-developer-id": "string with {variableId} variables escaped",
	...
	"welcome": "Hello {userFirstName}!"
}

```

--------------------------------

### Generate UI with Compliant Text

Source: https://developer.dittowords.com/mcp-reference/examples

Add this instruction to your agent's prompt to ensure it uses Ditto's style guides when generating new UI text. The agent will automatically call `get_styleguide_rules` before creating any user-facing strings.

```text
Use the style guides in Ditto to generate UI with compliant text.
```

--------------------------------

### Filtering Projects by Format

Source: https://developer.dittowords.com/feedback-support/changelog

Use the optional `format` query parameter to specify the output format for project data.

```URL
/projects/PROJECT_ID?format=flat
```

--------------------------------

### update_styleguide_rule

Source: https://developer.dittowords.com/mcp-reference/tools

Update an existing rule by ID (any field: name, description, examples, tags, enabled).

```APIDOC
## update_styleguide_rule

### Description
Update an existing rule by ID (any field: name, description, examples, tags, enabled).

### Method
PUT

### Endpoint
/styleguide/rules/{rule_id}

### Parameters
#### Path Parameters
- **rule_id** (string) - Required - The ID of the rule to update.

### Request Body
- **name** (string) - Optional - The new name of the rule.
- **description** (string) - Optional - The new description of the rule.
- **examples** (array) - Optional - A list of example strings.
- **tags** (array) - Optional - A list of tags associated with the rule.
- **enabled** (boolean) - Optional - Whether the rule is enabled.
```

--------------------------------

### OpenAPI Security Scheme Definition

Source: https://developer.dittowords.com/api-reference/components/create-components

Example of defining an API Key authentication scheme for securing API endpoints.

```yaml
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
```

--------------------------------

### Swift Code for .stringsdict Integration

Source: https://developer.dittowords.com/string-formats/ios

Swift code demonstrating how to use String.localizedStringWithFormat to integrate .stringsdict files. Shows correct argument order for pluralization and variables.

```swift
let localizedString = String.localizedStringWithFormat(
    NSLocalizedString(
        "cart",
        comment: "A description of the user's cart"
    ),
    // The first argument should always be an integer to determine which plural
    // form to use
    pluralcount,
    // Subsequent arguments should be provided in alphabetical order according
    // to the names of the Ditto Variables used in a given text item
    String(pluralcount),
    username,
)
```

--------------------------------

### API Success Response Example

Source: https://developer.dittowords.com/api-reference/components/patch-components

A successful API call to update a component will return a JSON object indicating success.

```json
{
  "success": true
}
```

--------------------------------

### iOS .stringsdict Format with Variant Metadata

Source: https://developer.dittowords.com/string-formats/ios

Example of .stringsdict format including variant metadata comments. Used for pluralized text localization.

```xml
<?xml version="1.0" encoding="utf-8"?>
<!-- Variant Name: French -->
<!-- Variant Description: Copy localized for native French speakers -->
<plist version="1.0">
   ...
```

--------------------------------

### Add Plural Forms to Component

Source: https://developer.dittowords.com/api-reference/components/patch-components

This example shows how to add plural forms for a component, defining different text for singular and plural instances.

```yaml
add_plurals:
  summary: Add plural forms
  value:
    updates:
      - developerId: component-id-1
        plurals:
          upsert:
            - form: one
              text: item
            - form: other
              text: items
```

--------------------------------

### Manual .mcp.json Configuration (Project Scope)

Source: https://developer.dittowords.com/mcp-reference/installation

Manually creates a .mcp.json file in the project root to configure the Ditto MCP server. Requires the DITTO_API_TOKEN environment variable.

```json
{
  "mcpServers": {
    "ditto": {
      "type": "http",
      "url": "https://api.dittowords.com/v2/mcp",
      "headers": {
        "Authorization": "token ${DITTO_API_TOKEN}"
      }
    }
  }
}
```

--------------------------------

### iOS .strings Format with Variant Metadata

Source: https://developer.dittowords.com/string-formats/ios

Example of .strings format including variant metadata comments for localization. Used for simple text localization.

```swift
/* Variant Name: French */
/* Variant Description: Copy localized for native French speakers */

"welcome.title" = "Welcome, %1$@!";
```

--------------------------------

### Add Ditto MCP Server (Project Scope)

Source: https://developer.dittowords.com/mcp-reference/installation

Shares the Ditto MCP configuration with the entire team by creating a .mcp.json file. This file should be checked into source control.

```bash
claude mcp add --scope project --transport http ditto https://api.dittowords.com/v2/mcp --header 'Authorization: token ${DITTO_API_TOKEN}'
```