Ditto API

📝
Ditto
Search…
📝
Third-party i18n Frameworks
Changelog
Ditto API
The Ditto API allows you to read and write information from your Ditto workspace.
Overview
The Ditto API currently supports read access of Ditto workspaces and is served over HTTPS. All endpoint URLs have the following base: https://api.dittowords.com. 
Authentication
To access any Ditto API endpoints, you'll need an API key. You can view, create, and revoke your API keys in your Account Settings. 
Each API key is attached to a specific user and can only be used to fetch information from that user's Ditto workspace.
Creating an API key
If you already have a Ditto account, you can create an API Key as follows:
1.Head to your Account Settings​
2.Under the section titled API Keys, click + Create key.
The User tab under the Account Settings page.
Using an API key
To use your API key to make a request to the Ditto API, you'll need to pass it in an Authorization header in all requests: 
'Authorization: token <YOUR_API_KEY>'

Here's an example request to Ditto's /projects endpoint:
curl GET 'https://api.dittowords.com/projects' \
		--header 'Authorization: token <YOUR_API_KEY>'
Only projects that have Developer Mode enabled are accessible via the API. Learn more about Developer Mode here.
Export Formats
Our API is most often used to integrate Ditto directly into development, and the needs of Ditto users often vary according to the type of application they're building and the ways in which their development toolchains are configured. 
To support diverse workflows, API endpoints that return text data can be configured to return that data in a variety of formats. 
If you're unsure whether or not a given endpoint supports different formats, please see the endpoint reference below.
full 
This is the default format that is returned if no format parameter is specified.
The full format is not recommended for integration into development. It's likely that it will no longer be the default format in future API versions.
Content-Type: text/json
{
  {
    "project_id": "[ID OF PROJECT",
    "exported_at": "[UTC TIME OF EXPORT]",
    "frames": { 
      "[FRAME ID]": {
        "frame_name": "[NAME OF FRAME]",
        "blocks": { 
          {
            "[BLOCK ID]": { 
              "[TEXT ID]": {
                "text": "[TEXT OF TEXT ITEM]",
                "status": "[STATUS OF TEXT ITEM]", // optional
                "notes": "[NOTES OF TEXT ITEM]", // optional
                "variables": {
                  "[VARIABLE NAME]": {
                        ... // variable properties: example, fallback, etc
                  }
                },
                "plurals": { // optional: only if plurals are enabled for text
                  "zero": "[TEXT FOR ZERO FORM]", // optional: depends on plural form being configured
                  "few": "[TEXT FOR FEW FORM]", // optional: depends on plural form being configured
                  "many": "[TEXT FOR MANY FORM]", // optional: depends on plural form being configured
                  "other": "[TEXT FOR OTHER FORM]", // optional: depends on plural form being configured
                },
                "tags": [ ... ], // optional: array of strings
                "variants": { // optional: only present if text has variant values
                  "[VARIANT ID]": {
                    "text": "[TEXT OF VARIANT]",
                    "variables": { ... } // see previous `variables` property,
                    "plurals": { ... } // see previous `plurals` property
                  }
                }
              },
              "[TEXT ID]": { ... }
            }
          },
          "[BLOCK ID]": { ... }
        },
        "otherText": [ // text not in blocks
          "[TEXT ID]": {
            "text": "[TEXT OF TEXT ITEM]",
            "status": "[STATUS OF TEXT ITEM]", // optional
            "notes": "[NOTES OF TEXT ITEM]", // optional
            "tags": [ ... ], // see previous `tags` property
            "variants": { ... } // see previous `variants` property
          },
          "[TEXT ID]": { ... }
        ]
      },
      "[FRAME ID]": { ... },
      ...
    }
  }
}
structured
Content-Type: text/json
{
  "[TEXT ID]": {
    "text": "[TEXT OF TEXT ITEM]",
    "status": "[STATUS OF TEXT ITEM]", // optional
    "notes": "[NOTES OF TEXT ITEM]", // optional
    "tags": [ ... ], // optional: array of strings
    "variables": {
      "[VARIABLE NAME]": {
            ... // variable properties: example, fallback, etc
      }
     },
    "plurals": { // optional: only if plurals are enabled for text
      "zero": "[TEXT FOR ZERO FORM]", // optional: depends on plural form being configured
      "few": "[TEXT FOR FEW FORM]", // optional: depends on plural form being configured
      "many": "[TEXT FOR MANY FORM]", // optional: depends on plural form being configured
      "other": "[TEXT FOR OTHER FORM]", // optional: depends on plural form being configured
    },
    "variants": { // optional: only present if text has variant values
      "[VARIANT ID]": {
      "text": "[TEXT OF VARIANT]",
      "variables": { ... } // see previous `variables` property,
      "plurals": { ... } // see previous `plurals` property
    }
  },
  "[TEXT ID]": { ... },
  ...
}
flat
Content-Type: text/json
{
  "[TEXT ID]": "[TEXT OF TEXT ITEM]",
  "[TEXT ID]": "[TEXT OF TEXT ITEM]",
  ...
}
android
This format corresponds to the Android resource files required for localization, documented here.
Text items in Ditto are mapped to <string> tags and given name values that correspond to a given text item's API ID with - characters replaced with _. An additional ditto_api_id field is also added with the original api id.
Variables in Ditto are mapped to <xliff:g> tags and given id and example values that correspond to a given variable's name and example values, respectively.
A text item with plurals will have a <plurals> tag generated for it, along with an <item> for each plural form that is configured in Ditto (note: <item id="other"> will always be generated). Plural items also support variables via <xliff:g> tags.
Although an example is shown below, please see the Android strings documentation and the Android localization documentation for a complete reference.
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
  <string name="welcome_text" ditto_api_id="welcome-text">Welcome to the app!</string>
  <string name="logout" ditto_api_id="logout">Logout</string>
</resources>
ios-strings
This format corresponds to the iOS .strings files that can be used for localization, documented here.
Notes associated with text items will be included as comments above a given key value pair
Variables in text items will be replaced with interpolation placeholders with a string format specifier
Content-Type: text/plain
"welcome-text" = "Welcome!";
​
/* This should only be used on the logout screen */
"logout" = "Logout";
Endpoints
get
https://api.dittowords.com
/project-names
List project names
get
https://api.dittowords.com
/projects
Fetch projects

Example Request
curl GET 'https://api.dittowords.com/projects?projectIds[]=xxx-xxx-xxx&projectIds[]=xxx-xxx-xxx' \
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
get
https://api.dittowords.com
/projects/:id
Fetch project by ID

Example Request
curl GET 'https://api.dittowords.com/projects/<DITTO_PROJECT_ID>' \
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
get
https://api.dittowords.com
/projects/:id/components
Fetch project components
curl GET 'https://api.dittowords.com/projects/<DITTO_PROJECT_ID>/components' \
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
get
https://api.dittowords.com
/variants
Fetch variants
curl GET 'https://api.dittowords.com/variants' \
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
get
https://api.dittowords.com
/components
Fetch components
# Request
curl GET 'https://api.dittowords.com/components' \
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
		
# Example Response
{
    "footer.about.blog": {
        "name": "Footer/About/Blog",
        "text": "Blog"
    },
    "footer.about.careers": {
        "name": "Footer/About/Careers",
        "text": "Careers"
    }
    ...
}
get
https://api.dittowords.com
/variables
Fetch variables
put
https://api.dittowords.com
/components
Update components
# Example Request
curl PUT 'https://api.dittowords.com/components?variant={variant_api_id}' \
		--header 'Authorization: token <YOUR_DITTO_API_KEY>' \
		--data '{ "data": { "text": "hello world" } }'
Additional Data Structures
Update Component Data
The shape that the request body should conform to for the Update components endpoint.
{
  "[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]"
      }
    ]
  }
}