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: 
1
'Authorization: token <YOUR_API_KEY>'
Copied!

Here's an example request to Ditto's /projects endpoint:
1
curl GET 'https://api.dittowords.com/projects' \
2
		--header 'Authorization: token <YOUR_API_KEY>'
Copied!
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
1
{
2
  {
3
    "project_id": "[ID OF PROJECT",
4
    "exported_at": "[UTC TIME OF EXPORT]",
5
    "frames": { 
6
      "[FRAME ID]": {
7
        "frame_name": "[NAME OF FRAME]",
8
        "blocks": { 
9
          {
10
            "[BLOCK ID]": { 
11
              "[TEXT ID]": {
12
                "text": "[TEXT OF TEXT ITEM]",
13
                "status": "[STATUS OF TEXT ITEM]", // optional
14
                "notes": "[NOTES OF TEXT ITEM]", // optional
15
                "variables": {
16
                  "[VARIABLE NAME]": {
17
                        ... // variable properties: example, fallback, etc
18
                  }
19
                },
20
                "plurals": { // optional: only if plurals are enabled for text
21
                  "zero": "[TEXT FOR ZERO FORM]", // optional: depends on plural form being configured
22
                  "few": "[TEXT FOR FEW FORM]", // optional: depends on plural form being configured
23
                  "many": "[TEXT FOR MANY FORM]", // optional: depends on plural form being configured
24
                  "other": "[TEXT FOR OTHER FORM]", // optional: depends on plural form being configured
25
                },
26
                "tags": [ ... ], // optional: array of strings
27
                "variants": { // optional: only present if text has variant values
28
                  "[VARIANT ID]": {
29
                    "text": "[TEXT OF VARIANT]",
30
                    "variables": { ... } // see previous `variables` property,
31
                    "plurals": { ... } // see previous `plurals` property
32
                  }
33
                }
34
              },
35
              "[TEXT ID]": { ... }
36
            }
37
          },
38
          "[BLOCK ID]": { ... }
39
        },
40
        "otherText": [ // text not in blocks
41
          "[TEXT ID]": {
42
            "text": "[TEXT OF TEXT ITEM]",
43
            "status": "[STATUS OF TEXT ITEM]", // optional
44
            "notes": "[NOTES OF TEXT ITEM]", // optional
45
            "tags": [ ... ], // see previous `tags` property
46
            "variants": { ... } // see previous `variants` property
47
          },
48
          "[TEXT ID]": { ... }
49
        ]
50
      },
51
      "[FRAME ID]": { ... },
52
      ...
53
    }
54
  }
55
}
Copied!
structured
Content-Type: text/json
1
{
2
  "[TEXT ID]": {
3
    "text": "[TEXT OF TEXT ITEM]",
4
    "status": "[STATUS OF TEXT ITEM]", // optional
5
    "notes": "[NOTES OF TEXT ITEM]", // optional
6
    "tags": [ ... ], // optional: array of strings
7
    "variables": {
8
      "[VARIABLE NAME]": {
9
            ... // variable properties: example, fallback, etc
10
      }
11
     },
12
    "plurals": { // optional: only if plurals are enabled for text
13
      "zero": "[TEXT FOR ZERO FORM]", // optional: depends on plural form being configured
14
      "few": "[TEXT FOR FEW FORM]", // optional: depends on plural form being configured
15
      "many": "[TEXT FOR MANY FORM]", // optional: depends on plural form being configured
16
      "other": "[TEXT FOR OTHER FORM]", // optional: depends on plural form being configured
17
    },
18
    "variants": { // optional: only present if text has variant values
19
      "[VARIANT ID]": {
20
      "text": "[TEXT OF VARIANT]",
21
      "variables": { ... } // see previous `variables` property,
22
      "plurals": { ... } // see previous `plurals` property
23
    }
24
  },
25
  "[TEXT ID]": { ... },
26
  ...
27
}
Copied!
flat
Content-Type: text/json
1
{
2
  "[TEXT ID]": "[TEXT OF TEXT ITEM]",
3
  "[TEXT ID]": "[TEXT OF TEXT ITEM]",
4
  ...
5
}
Copied!
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.
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
1
<?xml version="1.0" encoding="utf-8"?>
2
<resources>
3
  <string name="welcome_text">Welcome to the app!</string>
4
  <string name="logout">Logout</string>
5
</resources>
Copied!
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
1
"welcome_text" = "Welcome!";
2
​
3
/* This should only be used on the logout screen */
4
"logout" = "Logout";
Copied!
Endpoints
get
https://api.dittowords.com
/project-names
List project names
get
https://api.dittowords.com
/projects
Fetch projects

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

Example Request
1
curl GET 'https://api.dittowords.com/projects/<DITTO_PROJECT_ID>' \
2
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
Copied!
get
https://api.dittowords.com
/projects/:id/components
Fetch project components
1
curl GET 'https://api.dittowords.com/projects/<DITTO_PROJECT_ID>/components' \
2
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
Copied!
get
https://api.dittowords.com
/variants
Fetch variants
1
curl GET 'https://api.dittowords.com/variants' \
2
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
Copied!
get
https://api.dittowords.com
/components
Fetch components
1
# Request
2
curl GET 'https://api.dittowords.com/components' \
3
		--header 'Authorization: token <YOUR_DITTO_API_KEY>'
4
		
5
# Example Response
6
{
7
    "footer.about.blog": {
8
        "name": "Footer/About/Blog",
9
        "text": "Blog"
10
    },
11
    "footer.about.careers": {
12
        "name": "Footer/About/Careers",
13
        "text": "Careers"
14
    }
15
    ...
16
}
Copied!
get
https://api.dittowords.com
/variables
Fetch variables
put
https://api.dittowords.com
/components
Update components
1
# Example Request
2
curl PUT 'https://api.dittowords.com/components?variant={variant_api_id}' \
3
		--header 'Authorization: token <YOUR_DITTO_API_KEY>' \
4
		--data '{ "data": { "text": "hello world" } }'
Copied!
Additional Data Structures
Update Component Data
The shape that the request body should conform to for the Update components endpoint.
1
{
2
  "[API ID]": {
3
    "text": "[TEXT OF TEXT ITEM]",
4
    "notes": "[NOTES OF TEXT ITEM]", // optional
5
    "tags": [ ... ], // optional: array of strings
6
    "plurals": [ // optional: array of plural objects
7
      {
8
        "text": "[TEXT OF PLURAL FORM]",
9
        "form": "[one|two|zero|few|many|other]"
10
      }
11
    ]
12
  }
13
}
Copied!