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_nameand__variant-description - In the Android, iOS
.strings, and iOS.stringsdictformats, 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
variablesin conjunction with theflatformat
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
flatformat does not currently support variables. - Fixed a bug preventing falsy values (namely
0and"") from being properly interpolated.
- Added the
includeRichTextflag to the following endpoints (format must befullorstructured):/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
statusparameter in yourconfig.yml.
- Added
androidandios-stringsas available formats. To use these formats, specify them under theformatparamter in yourconfig.yml.
- Fixed a typo in an example in the documentation containing an incorrect usage of the
curlcommand.
- 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
flatexports 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
statusfield failed to properly filter returned data when specified in conjunction with theandroidorios-stringsformats.
- We exported two hooks that can be used for accessing synced data:
useDittoSingleTextanduseDittoComponent. These hooks are experimental and will likely undergo API changes in the future.
- Added the
statusfield to data returned from the/componentsand/projects/:id/componentsendpoints.
- Added support for including variables in payloads sent to the
PUT /componentsendpoint. - Fixed an issue with Android & iOS export formats not escaping special characters:
\n,\t,@,?,', and"characters are now properly escaped. - Added missing
xliffnamespace to exported Android.xmlfiles. - Fixed a bug with Android
.xmlexports that occurred with text items with API IDs that include the-character. Now, all-characters are replaced with_characters in thenameproperty of<string>and<plural>tags, and aditto_api_idproperty 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 removecommands and selecting the component library caused incorrect modifications to be made to the CLI's configuration file.
- Added an optional
ditto-dirinput parameter for projects that do not have thedittodirectory 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
formatquery parameter can now accept values ofandroidorios-strings. - Added
GET /variablesendpoint that returns the variables in the workspace of the requesting user. - Added the ability to filter by text item status by passing a
statusquery parameter in API requests. Supported by the following endpoints:GET /projectsGET /projects/:idGET /projects/:id/componentsGET /components
- Added
metaoption 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.ymlfile 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
variablesprop. - Our React SDK now supports displaying plural forms through the
countprop.
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
pullcommand no longer crashes when projects other than the component library are specified inconfig.yml - resolves a casing issue in the
project addcommand 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/componentscan now be used to fetch the components used in a project- Return format matches the
GET /componentsendpoint - Supports
formatandvariantparameters (the same as the/projects,/project/:id, and/componentsendpoints)
GET /componentscan now be used to fetch the components in a workspace- Supports
formatandvariantparameters (the same as the/projectsand/project/:idendpoints)
GET /projects/ditto_component_libraryhas been deprecated; the endpoint is still available, but references to it have been removed from the documentation.PUT /componentscan now be used to update the text of components in a workspace- Currently only supports updating variant text via the
variantquery parameter (an error will be thrown if not specified) - Currently only available to teams on
teamorenterpriseplans - Data is specified on
datakey 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
variantsoption is set and a format ofstructuredorflatis specified, output files will be written on a per-project per-variant basis - Data for
structuredandflatformats 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-reactnow 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, orcomponentIdvalues 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
flatandstructuredJSON 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
pullcommand is executed, all.jsonand.jsfiles are now removed from thedittofolder prior to new data being written - Support added for new options in
ditto/config.yml:variants:trueorfalse- If set to
true, data will be fetched for both base and variant text and stored in separate JSON files
format:flatorstructured- If specified, data will be fetched and stored in the specified format
- Refactored README
GET /variantswill now return names and API IDs for variants in the workspace associated with the requesting user.
- Support added for
flatandstructuredformats - Support added for passing a
variantvalue toDittoProvider - Bug fixes around support for integrating with workspace component libraries (as opposed to individual projects)
- Refactored README
- Refactored
ditto-sdkusage to integrate with a component library instead of an individual project - Added a language picker to showcase
ditto-reactandditto-clisupport for variants - Refactored README, including adding instructions for connecting the repo to a component library
- Fixed incorrect example of
/projectsusage in API Reference. TheprojectIdsquery parameter should be specified as follows:- Correct
?projectIds[]=<PROJECT_ID>&projectIds[]=<PROJECT_ID>
- Incorrect
?projectIds[]=<PROJECT_ID>,<PROJECT_ID>
GET /variantswill now return names and API IDs for variants in the workspace associated with the requesting user.
GET /projectsandGET /projects/:idnow 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 andstructuredformats, thevariantskey will not be included when thevariantparameter is provided.- Example:
/projects/<PROJECT_ID>?variant=xxx-xxx-xxx
GET /projects/:idwill not include top-levelprojectsandproject_xyzkeys- 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 /projectsandGET /projects/:idnow accepts an optional query parameter offormat, which can be eitherflatorstructured. 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/:idwill 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/:idwill now match the project JSON export from the web-app to include component information (is_compandcomponent_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
projectIdprop can be passed toDittoProviderorDitto- If passed to
DittoProvider, all descendantDittocomponents 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
DittoProviderandDitto, the value passed toDittowill take precedence - Breaking change: If a
Dittocomponent is rendered that is not provided aprojectIdvia direct prop orDittoContextancestor, an error will be thrown
- Upgraded
ditto-reactto version0.0.4 - Updated source to work with new
ditto-reactversion by passingprojectIdprops to all instances ofDittoContext
We've updated both our CLI and API to handle multiple projects.
GET /project-namesis 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/:idwill now return the structured JSON in a format compatible with multiple projectsGET /projectsis 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.ymlnow supports multiple projects.ditto-cli pullwill 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.ymlditto-cli project addditto-cli project remove- The regular
ditto-cli projectcommand will now function asditto-cli project add
GET /projectsnow includes the Component Library if Developer Mode is enabled for the Component LibraryGET /projects/:idwill return the Component Library as a structured JSON if the ID provided isditto_component_library
GET /projectsendpoint for fetching Ditto projects from workspaceGET /projects/:idendpoint for fetching content in Ditto project as structured JSON
Last modified 2h ago