Changelog
Ditto components with rich text can now be rendered natively by passing the
richText
property on either Ditto
or DittoComponent
.<Ditto componentId="shopping-cart" richText />
Endpoints for fetching project text now support an
exclude_components
query parameter. When
exclude_components=true
, only text items not associated with Ditto components will be returned from a given endpoint.The behavior of variables when exporting to mobile formats (
.strings
, .stringsdict
, and .xml
) has changed.Variables will now maintain a consistent ordering across base text, variant text, and plural forms; they're assigned an index according to the order of usage (starting with base text, and then variants), and that index is maintained through variant exports.
For example, consider the following text:
// Base Text
{{username}}, your role is {{role}}.
// Variant Text
Tú papel es {{role}}, {{username}}.
Previously, exports for the base text and variant text would cause format specifier indices to be reversed for the variables:
/* base-example.strings */
"text" = "%1$@, your role is %2$@.";
/* spanish-example.strings */
"text" = "Tú papel es %1$@, %2$@.";
To facilitate ease of integration into development, exports for variant text will now ensure that the format specifier indices match those in the base text:
/* base-example.strings */
"text" = "%1$@, your role is %2$@.";
/* spanish-example.strings */
"text" = "Tú papel es %2$@, %1$@.";
Support has been added for an
exclude_components
query parameter to the Fetch text by project id endpoint.
When set to true
, only text items not associated with components will be returned from the endpoint.- Small bug fix to ensure files aren't written to disk for empty API responses.
When exporting data for variants, variant metadata (name and description) is now included.
- In the JSON formats, two new meta keys are added at the top level:
__variant_name
and__variant-description
- In the Android, iOS
.strings
, and iOS.stringsdict
formats, a comment is added for each field at the top of the file
The
flat
format now supports rich text.Added support for specifying a list of formats in the
format
configuration property.v1.4.1 fixes a bug introduced in v1.4.0 which caused variables to ignore passed values.
Added the
import-components
command which enables component imports via a file through the CLI. For information about the command please refer to the documentation in the README.We've added the new
POST /components/file
endpoint to enable uploading components through the API.Add the ability to only match on components from a component folder. Must be used with v3.8.0 of the Ditto CLI.
Add
component-folders
command which lists component folders in your workspace. See the release here.We've added support for specifying the new
ios-stringsdict
format in the CLI configuration. See the release here.We clarified a small point of confusion with the documentation around the request payload expected for the Update component text variant endpoint.
The JSON payload should include a top-level
data
property:{
"data": {
"[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]"
}
]
}
}
}
- [DIT-3960] Add full ICU support by @azjgard in https://github.com/dittowords/cli/pull/58
- Adds ICU support
- Fixes a bug where pulling would fail on new initializations
Full Changelog: https://github.com/dittowords/cli/compare/v3.3.0...v3.5.0
v3.4.0 of the CLI has been published, which adds a
-v, --version
flag to output what version of the CLI is being run.We've published v1.4.0, which includes explicit support for
map
and list
variables, in addition to miscellaneous cleanup.We've added a
__type
property to variable output in our structured
export format; this enables simple discrimination between different types of variables:{
"some-variable-1": {
"example": "Hello world!",
"__type": "string"
},
"some-variable-2": {
"example": 100,
"__type": "number"
},
"some-variable-3": {
"text:" "Foo",
"url": "https://bar.com",
"__type": "hyperlink"
}
}
We've published v3 of the CLI, which focuses around a number breaking changes intended to better align default CLI behavior with Ditto best practices.
We've added a new page outlining supported versus unsupported use cases for the Ditto API: Usage Guidelines.
We've released two bug fixes specific to the Android XML export format:
We've released a new version of our API that includes some breaking changes. The old API endpoints are deprecated, and existing users should migrate to the new endpoints at their earliest convenience.
- Removed the deprecated the full format from the export modals on the project page and in the component library
Minor documentation update to add and emphasize a deprecation notice for the full format.
- it's not recommended for integrating Ditto into development
- it will be removed in future API versions
- Added support for using
variables
in conjunction with theflat
format
We added support to the web app for importing components from two new file formats:
- Android localization files (
.xml
) - iOS localization files (
.strings
)
- Updated README to clarify that the
flat
format does not currently support variables. - Fixed a bug preventing falsy values (namely
0
and""
) from being properly interpolated.
- Added the
includeRichText
flag to the following endpoints (format must befull
orstructured
):/projects
/projects/:id
/projects/:id/components
/components
/component-folders/:api_id/components
- Added the status filter as a configuration variable. To filter the fetched text by its status, you can now use the
status
parameter in yourconfig.yml
.
- Added
android
andios-strings
as available formats. To use these formats, specify them under theformat
paramter in yourconfig.yml
.
- Fixed a typo in an example in the documentation containing an incorrect usage of the
curl
command.
- Added information to the README about two supported environment variables:
DITTO_CONFIG_FILE
: used to specify an alternate file location for the CLI to read authentication information from. The default path is$HOME/.config/ditto
.DITTO_TEXT_DIR
: used to specify an alternate folder location for the CLI to write its output files to. The default path is./ditto
.
- Added sub-headings to divide the endpoints by the entity they're associated with, and implemented minor miscellaneous cleanup across the endpoint documentation
- Text items with plural values will have those plural values included in
flat
exports as individual key/value pairs; pluralized keys are structured like"[TEXT ID]_[PLURAL FORM]"
. See the flat format documentation for more details. - Fixed a bug where the
status
field failed to properly filter returned data when specified in conjunction with theandroid
orios-strings
formats.
- We exported two hooks that can be used for accessing synced data:
useDittoSingleText
anduseDittoComponent
. These hooks are experimental and will likely undergo API changes in the future.
- Added the
status
field to data returned from the/components
and/projects/:id/components
endpoints.
- Added support for including variables in payloads sent to the
PUT /components
endpoint. - Fixed an issue with Android & iOS export formats not escaping special characters:
\n
,\t
,@
,?
,'
, and"
characters are now properly escaped. - Added missing
xliff
namespace to exported Android.xml
files. - Fixed a bug with Android
.xml
exports that occurred with text items with API IDs that include the-
character. Now, all-
characters are replaced with_
characters in thename
property of<string>
and<plural>
tags, and aditto_api_id
property has been added to string and plural tags to serve as a reference to the original API ID.
- Fixed a bug when using the
project add
/project remove
commands and selecting the component library caused incorrect modifications to be made to the CLI's configuration file.
- Added an optional
ditto-dir
input parameter for projects that do not have theditto
directory in the root of the repository
- Added support for upserting plurals via the
PUT /components
.
- Added early support for exporting text data to Android and iOS Strings formats. All endpoints that support a
format
query parameter can now accept values ofandroid
orios-strings
. - Added
GET /variables
endpoint that returns the variables in the workspace of the requesting user. - Added the ability to filter by text item status by passing a
status
query parameter in API requests. Supported by the following endpoints:GET /projects
GET /projects/:id
GET /projects/:id/components
GET /components
- Added
meta
option flag in support of the Ditto GitHub Action release
- v0.1.0 released!
- Update some user-facing CLI messages to accurately reflect our new subdomain:
app.dittowords.com
(instead of the oldbeta.dittowords.com
)
- Allows users to override the output directory via a new environment variable
DITTO_TEXT_DIR
- When no projects are found in the
config.yml
file an additional help message displays about verifying that the projects have developer mode enabled
- Added better error handling for the niche edge case where an API request is made using the token of a user that has been removed from their workspace.
- Our React SDK now supports variable interpolation by passing in values through the
variables
prop. - Our React SDK now supports displaying plural forms through the
count
prop.
For more information about using variable interpolations and pluralization through our React SDK, check out our SDK documentation.
The CLI now supports reading API keys from an environment variable (
DITTO_API_KEY
).We deployed a bugfix release to fix issues introduced in the latest minor version of the package:
- the
pull
command no longer crashes when projects other than the component library are specified inconfig.yml
- resolves a casing issue in the
project add
command that was causing it to crash
We've added a new supported property to
ditto/config.yml
to allow explicitly specifying that the component library should be fetched and included in the CLI's output:components: true
This is now the preferred alternative to the old way of specifying the component library:
projects:
- name: Ditto Component Library
id: ditto_component_library
Our goal with this change is to make the CLI easier to use and understand by aligning it with the way things work in the Ditto web app, where the component library is fundamentally different from the projects in a workspace.
GET /projects/:id/components
can now be used to fetch the components used in a project- Return format matches the
GET /components
endpoint - Supports
format
andvariant
parameters (the same as the/projects
,/project/:id
, and/components
endpoints)
GET /components
can now be used to fetch the components in a workspace- Supports
format
andvariant
parameters (the same as the/projects
and/project/:id
endpoints)
GET /projects/ditto_component_library
has been deprecated; the endpoint is still available, but references to it have been removed from the documentation.PUT /components
can now be used to update the text of components in a workspace- Currently only supports updating variant text via the
variant
query parameter (an error will be thrown if not specified) - Currently only available to teams on
team
orenterprise
plans - Data is specified on
data
key in request body and must be in one of our three supported import formats: https://www.dittowords.com/docs/importing-string-jsons
Summary:
- Output files are now written to disk in several different ways according to how the CLI is configured; most notably, if the
variants
option is set and a format ofstructured
orflat
is specified, output files will be written on a per-project per-variant basis - Data for
structured
andflat
formats is saved without arbitrary top-level nesting - Files are only written for variants that contain values for the configured projects (no more empty files)
For a more in-depth description (with examples) of these changes and others in the release, see the full release notes here: https://github.com/dittowords/cli/releases/tag/v2.0.0.
ditto-react
now only works with CLI version 2.x.x — leaning into new CLI improvements allowed us to drastically reduce many areas of complex logical overhead- We made some stabilization improvements to the way that missing/invalid
frameId
,blockId
,textId
, orcomponentId
values are handled - We implemented significant refactoring in several areas of the project
For a more in-depth description of these changes, see the full release notes here: https://github.com/dittowords/ditto-react/releases/tag/v1.0.0
- We added a new branch that showcases how Ditto can be integrated into a project with
react-i18next
: https://github.com/dittowords/ditto-demo/tree/react-i18next - We updated dependencies to the latest versions of the Ditto CLI (v2.0.0) and Ditto React (v1.0.0)
- We fixed a bug with the API (and in-app exports) that included hidden text in
flat
andstructured
JSON exports. Now, hidden text will correctly not be included in these export formats!
- We included the files to import into the component library separately from where they'd be synced via the CLI
- We included more instructions on linking the demo app with its corresponding design file
- Refactored API documentation to be easier to navigate and communicate critical concepts more clearly
- When the
pull
command is executed, all.json
and.js
files are now removed from theditto
folder prior to new data being written - Support added for new options in
ditto/config.yml
:variants
:true
orfalse
- If set to
true
, data will be fetched for both base and variant text and stored in separate JSON files
format
:flat
orstructured
- If specified, data will be fetched and stored in the specified format
- Refactored README
GET /variants
will now return names and API IDs for variants in the workspace associated with the requesting user.
- Support added for
flat
andstructured
formats - Support added for passing a
variant
value toDittoProvider
- Bug fixes around support for integrating with workspace component libraries (as opposed to individual projects)
- Refactored README
- Refactored
ditto-sdk
usage to integrate with a component library instead of an individual project - Added a language picker to showcase
ditto-react
andditto-cli
support for variants - Refactored README, including adding instructions for connecting the repo to a component library
- Fixed incorrect example of
/projects
usage in API Reference. TheprojectIds
query parameter should be specified as follows:- Correct
?projectIds[]=<PROJECT_ID>&projectIds[]=<PROJECT_ID>
- Incorrect
?projectIds[]=<PROJECT_ID>,<PROJECT_ID>
GET /variants
will now return names and API IDs for variants in the workspace associated with the requesting user.
GET /projects
andGET /projects/:id
now accept an optional query parameter ofvariant
; when provided, the data exported will be specific to the variant with an API ID that matches the parameter's value. For default andstructured
formats, thevariants
key will not be included when thevariant
parameter is provided.- Example:
/projects/<PROJECT_ID>?variant=xxx-xxx-xxx
GET /projects/:id
will not include top-levelprojects
andproject_xyz
keys- Example request:
GET /projects/123
- Example response before change:
{ projects: { project_123: { text_item: "Hello World", ... }}}
- Example response after change:
{ text_item: "Hello World", ... }
GET /projects
andGET /projects/:id
now accepts an optional query parameter offormat
, which can be eitherflat
orstructured
. If no format is provided, the full JSON of the project will be returned with blocks and frames.- Example:
/projects/<PROJECT_ID>?format=flat
With the recent release of Variants for Components, we've included them in both exports from our web-app and the JSON response from the API.
GET /projects/:id
will now return component variants. This applies both for when fetching projects or when fetching the component library (i.e.id = ditto_component_library
)GET /projects/:id
will now match the project JSON export from the web-app to include component information (is_comp
andcomponent_api_id
) in the text object
We've updated our React library and our demo project to work with the multi-project JSON structure that the CLI now saves in
text.json
.- A new
projectId
prop can be passed toDittoProvider
orDitto
- If passed to
DittoProvider
, all descendantDitto
components will default to pulling text from the associated project - If passed to
Ditto
, the component will pull text from the associated project - If passed to both
DittoProvider
andDitto
, the value passed toDitto
will take precedence - Breaking change: If a
Ditto
component is rendered that is not provided aprojectId
via direct prop orDittoContext
ancestor, an error will be thrown
- Upgraded
ditto-react
to version0.0.4
- Updated source to work with new
ditto-react
version by passingprojectId
props to all instances ofDittoContext
We've updated both our CLI and API to handle multiple projects.
GET /project-names
is the new name of the previous GET /projects endpoint. Just as before, this will return the names and IDs of projects in your Ditto workspace with Developer Mode turned onGET /projects/:id
will now return the structured JSON in a format compatible with multiple projectsGET /projects
is a new endpoint that will return the content of multiple projects (specified via the query parameterprojectIds
) as a single JSON object
- We've updated the CLI to handle syncing multiple projects in a single directory! This means several things:
/ditto/config.yml
now supports multiple projects.ditto-cli pull
will pull all projects in the current directory's/ditto/config.yml
- We've added two new commands to add and remove projects from
/ditto/config.yml
ditto-cli project add
ditto-cli project remove
- The regular
ditto-cli project
command will now function asditto-cli project add
GET /projects
now includes the Component Library if Developer Mode is enabled for the Component LibraryGET /projects/:id
will return the Component Library as a structured JSON if the ID provided isditto_component_library
GET /projects
endpoint for fetching Ditto projects from workspaceGET /projects/:id
endpoint for fetching content in Ditto project as structured JSON
Last modified 2h ago