Files

Output Directory

The CLI outputs data from Ditto by writing files to disk. By default, these files are written to a ./ditto folder relative to the current working directory, but the location of the output files can be customized by defining the outDir property in your config.yml file or by setting the environment variable DITTO_OUT_DIR.

`./ditto` Directory

By default, this directory houses the configuration file (./ditto/config.yml) used by the CLI and is also the default write destination for any output files the CLI writes to disk. You can override the default location of the config file by using the --config flag when running any command or by setting the environment variable DITTO_PROJECT_CONFIG_FILE . Legacy Ditto users can use the config override path to support maintaining separate config files for the legacy and current versions of Ditto within the same application. If you run the CLI and the resolved config file does not exist, the CLI will automatically create a default config.yml file at the path specified.

String File Naming Conventions

All string files created will generally adhere to the following template:

{project_id}___{variant_id}.{extension}

project_id: the Developer ID of the project.
variant_id: the Developer ID of a variant or base for files generated for non-variant text
extension: the file extension that corresponds to the configured format(s) (e.g., json, xml, strings, stringsdict)

If components is included in the config, a single, combined file for all fetched components will also be created for each variant with the format components__{variant_id}.{extension}. To keep cross-platform behavior consistent, file names will be fully lowercase, have whitespace replaced with hyphens, and have non-word characters (with the exception of - and _) removed.

Format-specific Files

JSON

If one or more JSON string formats are configured, a series of json files will be generated, on a project-variant/components-variant pair basis. Generally each file will follow the shown format:

{
  "text-item-developer-id": "string with {{variableId}} variables escaped",
  ...,
  "text-item-with-plural-dev-id": "string with {{count}} characters",
  "text-item-with-plural-dev-id_other": "string with {{count}} characters",
  "text-item-with-plural-dev-id_one": "string with a character",
	...,
  "welcome": "Hello {{userFirstName}}!"
}

Additionally, a variables.json file will be generated that contains information about any variables used within the fetched text. The file has the following format:

{
  "text-variable-id": {
    "example": "example_value",
    "fallback": "default_value"
  },
  "number-variable-id": {
    "example": "1",
    "fallback": "10"
  },
  "link-variable-id": {
    "text": "URL display text",
    "url": "https://dittowords.com"
  },
  "list-variable-id": ["value1", "value2", "value3"],
  "map-variable-id": {
    "key1": "value1",
    "key2": "value2",
    "key3": "value3"
  }
}

Android XML

If android format is configured for an output, a series of .xml files will be generated, on a project-variant/components-variant pair basis. Generally each file will follow the shown format:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
  <string name="text-item-developer-id" ditto_api_id="text-item-developer-id">string with <xliff:g id="variableId" example="example_value">%1$s</xliff:g> variables</string>
  <string name="continue" ditto_api_id="continue">Continue</string>
  <string name="email" ditto_api_id="email">Email</string>
  <string name="hello" ditto_api_id="hello">Hello, <xliff:g id="FirstName" example="John">%1$s</xliff:g></string>
  <string name="log_in" ditto_api_id="log-in">Log In</string>
  <string name="save" ditto_api_id="save">Save</string>
  <string name="submit" ditto_api_id="submit">Submit</string>
  <plurals name="the_one_ring" ditto_api_id="the-one-ring">
    <item quantity="many">The <xliff:g id="count__1" example="4">%1$s</xliff:g> rings to rule them all</item>
    <item quantity="few">A few rings to rule them all</item>
  </plurals>
  <string name="welcome" ditto_api_id="welcome">Welcome, <xliff:g id="FirstName" example="John">%1$s</xliff:g>!</string>
</resources>

iOS Strings

If iOS Strings format is configured, a series of .strings files will be generated, on a project-variant/components-variant pair basis. Generally each file will follow the shown format:

"text-item-developer-id" = "string with %1$@ variables";

"continue" = "Continue";

"email" = "Email";

"hello" = "Hello, %1$@";

"log-in" = "Log In";

"save" = "Save";

"submit" = "Submit";

"welcome" = "Welcome, %1$@!";

iOS StringsDict

If iOS StringsDict format is configured, a series of .stringsdict files will be generated, on a project-variant/components-variant pair basis. Generally each file will follow the shown format:

<?xml version="1.0" encoding="utf-8"?>
<plist version="1.0">
  <dict>
    <key>the-one-ring</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>The one ring to rule them all</string>
            <key>other</key>
            <string>The %2$@ rings to rule them all</string>
        </dict>
    </dict>
  </dict>
</plist>

Framework-specific Files

Within each output format, an optional framework can be provided. Frameworks come in two kinds:

i18next and vue-i18n generate the standard flat JSON strings files (see Format-specific Files above) plus additional driver files to assist with using those strings files with the corresponding library.
icu and arb don’t generate any additional files. Instead, they change the shape of the JSON string values themselves — using ICU message format syntax for pluralization and variable interpolation. See the JSON string format docs for the exact content shape each one produces.

i18next

Formats supported: JSON Supported Properties:

`type: “commonjs” | “module” (default “commonjs”)`

By default, additional javascript files will be generated using commonjs syntax. This property configures the output to use commonjs or module syntax in the generated files. Details: Generates an additional javascript file that imports the generated strings files, and exports an object with the json strings grouped by their variants. If included, components will always be applied last.

// CommonJS
const exampleProject1Base = require("./example-project-1__root__base.json");
const exampleProject1Spanish = require("./example-project-1__root__spanish.json");
const exampleProject2Base = require("./example-project-2__base.json");
const exampleProject2Spanish = require("./example-project-2__spanish.json");
const componentsBase = require("./components__base.json");
const componentsSpanish = require("./components__spanish.json");

module.exports = {
  base: {
    ...exampleProject1Base,
    ...exampleProject2Base,
    ...componentsBase,
  },
  spanish: {
    ...exampleProject1Spanish,
    ...exampleProject2Spanish,
    ...componentsSpanish,
  },
};

// ESM
import exampleProject1Base from "./example-project-1__root__base.json";
import exampleProject1Spanish from "./example-project-1__root__spanish.json";
import exampleProject2Base from "./example-project-2__base.json";
import exampleProject2Spanish from "./example-project-2__spanish.json";
import componentsBase from "./components__base.json";
import componentsSpanish from "./components__spanish.json";

export default {
  base: {
    ...exampleProject1Base,
    ...exampleProject2Base,
    ...componentsBase,
  },
  spanish: {
    ...exampleProject1Spanish,
    ...exampleProject2Spanish,
    ...componentsSpanish,
  },
};

vue-i18n

Formats supported: JSON Functions very similarly and accepts all the same config properties as the i18next framework. The main difference is variable interpolation uses single brackets instead of double.

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

icu

Formats supported: JSON No additional properties are supported. Rather than generating an additional driver file, this framework changes the generated JSON string files to use ICU message format syntax for variable interpolation and pluralization, instead of the default flat JSON shape.

{
  "onboarding.header.title": "Welcome, {username}!",
  "cart.count": "{count, plural, =0 {No items in the cart} =1 {One item in the cart} other {{count} items in the cart}}"
}

See ICU JSON for the full content shape, including how Map/List variables and plurals are represented.

arb

Formats supported: JSON No additional properties are supported. Generates ARB (Application Resource Bundle) files instead of the default flat JSON shape — the format used by Flutter’s intl package. Message text uses the same ICU message format syntax as the icu framework, plus @-prefixed metadata entries for variable placeholders and text item notes, and a top-level @@locale key when a base or variant locale is known.

{
  "@@locale": "en",
  "cart.count": "{count, plural, =0 {No items in the cart} =1 {One item in the cart} other {{count} items in the cart}}",
  "@cart.count": {
    "placeholders": {
      "count": { "type": "num" }
    }
  }
}

See ARB JSON for the full content shape — including a note on why @@locale is the only thing identifying a generated ARB file’s language, and where to configure it.

Ditto-generated Files

iOS Locale Directories + Ditto.swift

If iosLocales is configured at the root level of the project config, a Ditto.swift file will be auto-generated in conjunction with the respective locale .lproj directories.

import SwiftUI

struct Ditto {
    static func getBundle(_ locale: String? = nil) -> Bundle {
        var bundle: Bundle? = nil
        if (locale != nil) {
            let path = Bundle.main.path(forResource: locale, ofType: "lproj")
            if (path != nil) {
                bundle = Bundle(path: path!)
            }
        }
        return bundle ?? Bundle.main
    }

    /// [Open component in Ditto](http://app.dittowords.com/library?selectedLibraryComponentIds=<component-id>)
    ///
    /// - Returns: The localized string for the Ditto identifier "continue"
    public static func continue(_ localeOverride: String? = nil) -> String {
        String.localizedStringWithFormat(NSLocalizedString("continue", tableName: "components", bundle: getBundle(localeOverride), comment: ""))
    }

    /// [Open component in Ditto](http://app.dittowords.com/library/<folder-id>?selectedLibraryComponentIds=<component-id>)
    ///
    /// - Returns: The localized string for the Ditto identifier "hello"
    public static func hello(_ localeOverride: String? = nil, FirstName: String) -> String {
        String.localizedStringWithFormat(NSLocalizedString("hello", tableName: "components", bundle: getBundle(localeOverride), comment: ""), FirstName)
    }

    struct myDittoProject {
        /// [Open text item in Ditto](http://app.dittowords.com/projects-beta/<project-id>?viewState=text&selectedTextItemIds=<text-item-id>)
        ///
        /// - Returns: The localized string for the Ditto identifier "email"
        public static func email(_ localeOverride: String? = nil) -> String {
            String.localizedStringWithFormat(NSLocalizedString("email", tableName: "my-ditto-project", bundle: Ditto.getBundle(localeOverride), comment: ""))
        }

        /// [Open text item in Ditto](http://app.dittowords.com/projects-beta/<project-id>?viewState=text&selectedTextItemIds=<text-item-id>)
        ///
        /// - Returns: The localized string for the Ditto identifier "submit"
        public static func submit(_ localeOverride: String? = nil) -> String {
            String.localizedStringWithFormat(NSLocalizedString("submit", tableName: "my-ditto-project", bundle: Ditto.getBundle(localeOverride), comment: ""))
        }
    }
}

By default, Ditto.swift and the .lproj directories are placed at the root-level outDir, alongside any other configured outputs. Configuring iosLocalesOutDir sends them to a separate directory instead — useful since iOS output typically needs to live somewhere different in a codebase than other platforms’ output (e.g., inside an Xcode project’s source directory, rather than a general assets folder). Example:

outDir: "./ditto"
iosLocalesOutDir: "./MyApp/Localization"

iosLocales:
  - base: en
  - spanish: es

outputs:
  - format: ios-strings
  - format: android

.
├── MyApp/
│   └── Localization/
│       ├── Ditto.swift
│       ├── en.lproj/
│       │   ├── my_project.strings
│       │   └── components.strings
│       └── es.lproj/
│           ├── my_project.strings
│           └── components.strings
└── ditto/
    ├── my_project___base.xml
    └── components__base.xml

The ios-strings output’s .lproj directories and Ditto.swift are written to ./MyApp/Localization (because of iosLocalesOutDir), while the unrelated android output still writes to the root-level outDir (./ditto).

Android Locale Directories

If androidLocales is configured at the root level of the project config, android-format XML files will be organized into the standard Android locale-qualified resource directories (values-<locale>/), instead of being written flat with a variant suffix. Unlike iOS, Android already has a default resource directory (values/, with no locale qualifier) that the platform falls back to automatically. Because of this, base text doesn’t need its own entry in androidLocales the way it does for iosLocales — it’s always written to values/ automatically. Only variants you want organized into a locale-specific directory need to be mapped. Example:

androidLocales:
  - spanish: es
  - french: fr

outputs:
  - format: android

This configuration will generate:

./ditto/
├── values/
│   ├── my_project.xml
│   └── components.xml
├── values-es/
│   ├── my_project.xml
│   └── components.xml
└── values-fr/
    ├── my_project.xml
    └── components.xml

Variants not mapped in androidLocales are written to the output directory with their variant suffix instead (e.g., my_project___german.xml), the same as unmapped variants with iosLocales. By default, the values/ and values-<locale>/ directories are placed at the root-level outDir, alongside any other configured outputs. Configuring androidLocalesOutDir sends them to a separate directory instead — useful since Android output typically needs to live somewhere different in a codebase than other platforms’ output (e.g., inside an Android module’s res/ directory). Example:

outDir: "./ditto"
androidLocalesOutDir: "./app/src/main/res"

androidLocales:
  - spanish: es
  - french: fr

outputs:
  - format: android
  - format: ios-strings

.
├── app/
│   └── src/
│       └── main/
│           └── res/
│               ├── values/
│               │   ├── my_project.xml
│               │   └── components.xml
│               ├── values-es/
│               │   ├── my_project.xml
│               │   └── components.xml
│               └── values-fr/
│                   ├── my_project.xml
│                   └── components.xml
└── ditto/
    ├── my_project___base.strings
    └── components__base.strings

The android output’s values/ and values-<locale>/ directories are written to ./app/src/main/res (because of androidLocalesOutDir), while the unrelated ios-strings output still writes to the root-level outDir (./ditto).

Overview

API Reference

CLI Reference

Agent Setup Package

MCP Reference

Ditto Specs CLI Reference

Additional Tools

Legacy

Output Directory

`./ditto` Directory

String File Naming Conventions

Format-specific Files

JSON

Android XML

iOS Strings

iOS StringsDict

Framework-specific Files

i18next

`type: “commonjs” | “module” (default “commonjs”)`

vue-i18n

icu

arb

Ditto-generated Files

iOS Locale Directories + Ditto.swift

Android Locale Directories

​Output Directory

​./ditto Directory

​String File Naming Conventions

​Format-specific Files

​JSON

​Android XML

​iOS Strings

​iOS StringsDict

​Framework-specific Files

​i18next

​type: “commonjs” | “module” (default “commonjs”)

​vue-i18n

​icu

​arb

​Ditto-generated Files

​iOS Locale Directories + Ditto.swift

​Android Locale Directories

Output Directory

`./ditto` Directory

String File Naming Conventions

Format-specific Files

JSON

Android XML

iOS Strings

iOS StringsDict

Framework-specific Files

i18next

`type: “commonjs” | “module” (default “commonjs”)`

vue-i18n

icu

arb

Ditto-generated Files

iOS Locale Directories + Ditto.swift

Android Locale Directories