Text Formats
To support diverse workflows that integrate Ditto into development, Ditto API endpoints that return text can send responses in a number of different formats.
If you're unsure whether or not a given endpoint supports format specification, please see the endpoint reference.
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
},
// This field is only included if `?includeRichText=true`
// is passed as a query parameter. Learn more:
// https://www.dittowords.com/docs/rich-text
"rich_text": "[HTML CONTENT OF TEXT ITEM]"
},
"[TEXT ID]": { ... },
...
}
Content-Type:
text/jsonThis format is only available for the component library.
1
{
2
"onboarding": {
3
"header": {
4
"title": "Welcome!",
5
"subtitle": "We're happy to have you here"
6
},
7
"body": {
8
"CTA": "Let's get started"
9
}
10
},
11
"authentication": {
12
"new-user-cta": "Create an account",
13
"existing-user-cta": "Sign in"
14
},
15
"toast": "Thanks for signing up!"
16
}
Component IDs are split according to the "forward slash" replacement character in a workspace's component ID configuration; each part of the ID split using this delimiter translates to a layer of depth in the generated
nested output.Assuming a "forward slash" replacement character of
., the JSON above would be generated from the following component IDs:onboarding.header.title
onboarding.header.subtitle
onboarding.body.CTA
authentication.new-user-cta
authentication.existing-user-cta
toast
The
nested export format is reverse-compatible with the nested import format: given the same workspace configuration, importing the nested JSON shown in this example will result in components being created with the component IDs listed above.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>
- Text items in Ditto are mapped to
<string>tags and givennamevalues that correspond to a given text item's API ID with-characters replaced with_. An additionalditto_api_idfield is also added with the original api id. - Variables in Ditto are mapped to
<xliff:g>tags and givenidandexamplevalues that correspond to a given variable's name andexamplevalues, 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 above, please see the Android strings documentation and the Android localization documentation for a complete reference.
Content-Type: text/plain
"welcome-text" = "Welcome!";
/* This should only be used on the logout screen */
"logout" = "Logout";
- 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
Deprecated formats are not recommended for integration into development and are unavailable in the latest API version.
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]": { ... },
...
}
}
}
Last modified 4d ago