<- Back to all posts

A Developer's Quick Guide to Integrating Ditto

Jessica Ouyang
|
September 15, 2021

As we expand our developer integrations, we've heard from more and more engineers that want to integrate Ditto on their teams.

Tired of opening PRs and tickets just for copy edits, hunting around in the codebase for different occurrences of strings, and manually checking and updating translation files, developers have reached out to use Ditto as a way to manage the strings they have in production.

We've recently launched a few core features in Ditto to make it just as easy for a developer to get up and running as a designer or writer. From syncing edits to existing strings to componentizing text and integrating with localization tools, we wanted to share a quick guide for developers on getting started with Ditto.

How we think about text end-to-end 🤔

We built Ditto with the intention of providing a single source of truth for product copy in all of its stages — from draft to design to production — and eliminating the copy and paste of product copy as it exists in current workflows: scattered between docs, sheets, mockups, and tickets.

We wanted to treat developers as first-class citizens in the product copy process, with workflows just as crucial as writers, designers, and PMs. We built our developer-facing features and integrations with the core intent of reducing time spent by developers in updating or implementing copy by allowing engineers to fetch up-to-date product copy directly into development.

Being developer-first 👩🏻‍💻

Building a solution that puts developers first required iterating on both (1) how new copy was passed between stakeholders and introduced into the product and (2) how existing strings were edited, translated, and maintained.

Initially, Ditto served the process of introducing and iterating upon new text. New copy typically gets written and passed along in the direction of draft → design → production, and our initial feature set targeted this workflow: importing from a design file using our Figma plugin to a Ditto project and then syncing that text to production with our API/CLI. Although our developer integrations functioned well in allowing for teams to integrate text from mockups into development, we wanted it to be just as easy to integrate and sync existing strings in our ecosystem.

As a team, we decided to work on ways developers could have an easy entry point into our product. This week, we introduced the ability to import string JSONs into Ditto as text components. We're super excited that this now allows teams to:

  1. Sync and manage strings in development directly in Ditto
  2. Use (and reuse!) strings in production as components in design files

We built this feature upon a core concept we heard over and over again from developer teams using Ditto: decoupling the copy and code.

Teams were transitioning away from hard-coding strings and treating product text as its own entity by pulling it out into their own files. It was especially common practice among established teams, as they had to adapt and implement solutions for the different challenges related to product copy and software development: state- and audience-based text, pluralizations, localizations, variable interpolations, and more.

We're really excited about what the ability to integrate Ditto from development first means for everyone involved in the product copy workflow. This guide will take you through how you can integrate Ditto into your development workflow (with or without Figma files!) in just a few minutes. 🥳

Step 1: Importing your strings 😎

To bring your existing strings into the Ditto ecosystem, import them into your component library via our JSON file import. Components generated from imported strings will have API IDs matching those in the file they were imported from — meaning you won't have to change any keys in production once you integrate Ditto!

If Developer Mode is turned on in your component library, you can import a JSON of strings by clicking the "New Component" button.

As a brief refresher, components are text items that are synced across projects and stored in the component library for your workspace. With components, repeated instances of text across your product can be referenced with a single string ID.

As product text in development stored in JSONs is typically already deduped and reused across the codebase, bringing strings in as text components in Ditto allows you to do the same, across design and development.

If you currently have text localized in different language-based files (i.e. fr.json, en.json, es.json, etc.), you can also bring them in as variants to components as long as you import the file in its primary language first.

Once strings have been brought into Ditto via the component import, Ditto allows you to:

  • Have a user interface for editing text and their translations (rather than having to edit strings in production manually)
  • Track all edits and their authors
  • Add metadata like tags and notes
  • Reuse production text in design files (and as a linter!) — see Step 3

Step 2. Sync edits back to development using our API ⚡️

Using our API, you can pull any edits made to the strings back into development. Just specify the component library as the project to fetch from (with the id ditto_component_library), and you can immediately pull down the up-to-date copy in several different JSON formats (flat, structured, or full).

Once you've hooked up your JSONs to be updated via our API, your job here is done! 🎉 You can now use Ditto as a UI to manage the strings currently being used in development. This also means non-developers can directly edit product copy through Ditto — without having to ping developers to hunt down and update strings.

Because the keys from the imported JSON match the API IDs of the generated components, you won't have to change how the keys are fetched in your front-end.

If you're using a translation management system (TMS) for your app like Lokalise or Phrase, our flat and structured JSON formats (and variant-based export!) can be immediately brought into a TMS to reflect up-to-date text in different languages.

For more information on using our API and developer integrations to sync updates to strings, check out our developer docs.

(Optional) Step 3: Using Components in Design Files 🌐

We're super excited about JSON imports as they allow developers to immediately integrate Ditto into their development process without needing to first figure out how Ditto integrates into design files. However, we're even more excited about how strings in production can function as components after designer buy-in!

Once the strings in production have been imported into Ditto as components, you can use them the same way as any other components in Ditto, meaning:

  • Designers and writers can reuse text in production in their designs
  • You can sync edits made to the strings across design files (new and old!)
  • You can use your strings to lint text in designs using component suggestions
  • You can effectively track where strings are being used in mockups
Components can lint text in design files via component suggestions — in both the web-app and our Figma plugin! (pictured above)

Wrapping up 🧙‍♀️

We hope this is guide can serve as a quick walkthrough of how you can integrate Ditto into development — in hopefully just a few minutes! — to serve as an interface to manage product text.

We're constantly amazed by the ways teams have used Ditto in development to power the text that users see in their product. Product copy exists from end-to-end — and requires collaboration across so many stakeholders, developers included.

We're excited to make Ditto easier for developers to bring onto their own teams, and our existing developer integrations are just the start. If you have any feedback on how Ditto can better fit into your team's developer workflows, please reach out — we're all ears! 🤗