<- Back to all posts

The All-In-One Guide to Localizing with Ditto

Jessica Ouyang
March 9, 2022

As teams integrate Ditto as a single source of truth for their product text (from design to review to development to localization!), we've seen Ditto scale flexibly to cover all kinds of workflows — including integrating full-circle with translation workflows.

In this blog post, we wanted to share two of the main ways we’ve seen teams use Ditto to localize their text, as well as the key ways Ditto can help streamline the entire process. In this post, we’ll cover:

     1. Components and Variants for localization

     2. Localizing with just Ditto

     3. Localizing with Ditto and a Translation Management System (TMS)

🧠 How does translated text work in Ditto?

A core functionality of Ditto is allowing teams to systemize their product text. Two features in Ditto are key to understanding how that text (and its translations!) function as a system in Ditto: components and variants.

👉 Components

Components are text items that are synced across projects and stored in the Component Library for your workspace. Edits to the text or meta-data of a component propagate to all of its instances.

This means that if a text item (for example a CTA or an error message) in your product is currently repeated across multiple product areas or Figma mockups, you’d only need to edit the text once and the edit will sync across all of the individual instances.

👉 Variants

Variants in Ditto allow teams to write and manage text variations. Teams commonly use variants for localization — a text item might be a French or Japanese variant — but variants can cover anything from state-based text to A/B tests and explorations.

Variants can be previewed (or applied) directly to the designs so that teams can quickly see how translated text fits in the UI.

Variants and components work together to help teams save time with translations. When you add a variant to a component, it applies to all of the component’s instances. This means, for example, that if you’ve already translated a CTA in one place, you won’t have to translate it again in the future.

Regardless of how you use Ditto to manage localization (whether fully in Ditto or with a TMS), Ditto reduces the time and money spent by eliminating duplicated translations. Rather than translating screen-by-screen or retranslating existing phrases, teams using Ditto can translate component by component.

🌏 Localizing with Ditto

Depending on your team’s current workflow and tech stack, you can use Ditto to localize in one of two ways — (1) with just Ditto or (2) with Ditto and a TMS.

With both of these options, Ditto provides a seamless way for teams to bring out the latest text from design files, manage text keys, and track edits to text. We’ll dive into both of these options, as well as why you might choose one or the other.

☝️ Option 1: Localizing with just Ditto

Many teams use Ditto to manage their localization in its entirety — from design all the way to development. This can be a good option if your translations are currently managed in-house and if your team isn’t currently using a translation management system (TMS).

The basic Ditto workflow to integrate a single source of truth for product copy from design to development looks like this:

Using variants in Ditto, you can localize your team’s product text in the same workflow. By creating language-based variants, you can preview translations in the designs and generate localization files for development.

Our API and CLI can fetch the text in Ditto into variant-specific JSON files, which keep the same text keys across variants. These files can be easily swapped to localize text in the product.

As a whole, the workflow to localize with Ditto isn’t very different from the core Ditto workflow to sync text from design to production:

Ditto’s JSON files are also directly compatible with internationalization frameworks like i18next. To check out a sample project integrating Ditto with React i18next, check out our example React i18next app.

✌️ Option 2: Localizing with Ditto and a TMS

You can also use Ditto in conjunction with a TMS to bring translations into your team’s Ditto ecosystem. This can be a good option if your team is currently using a TMS, or if your team is looking to utilize TMS-specific translation features such as machine translation or a TMS’s 3rd-party translators.

There are a couple of ways you can integrate a TMS to translate the text from Ditto. We’ll be diving into three ways you can set this up, but Ditto should be flexible enough to fit into other workflows as well! Keep in mind that different TMS’s have different features, which may not be applicable across all of these workflows.

You can integrate Ditto and a TMS by setting up the TMS to ingest the JSON files created by Ditto. After text is ingested and translated in the TMS [1], you can also write it back to Ditto using our API’s PUT endpoint [2], which allows the translations to be used in other places or previewed in the design.

Instead of using Ditto to fetch translations in development, you can integrate a TMS with Ditto to manage the translation process [A] and rely on the TMS to surface text/translations to development. This can be helpful if your product is already reliant on a TMS to serve the product text [B] and aren’t looking to transition away, or if your TMS supports specific file formats that Ditto doesn’t yet support.

Like in the last setup, after text is translated in the TMS, teams can bring translated text back into Ditto using the Ditto API [C].

Lastly, removing the step where translated text gets brought back into Ditto, you can also use Ditto to manage the text up until the point in which it needs to get translated. Although you wouldn’t be able to manage or preview translations in Ditto, Ditto still provides a seamless way for teams to manage text in their base language and bring out the text for translation.

🔮 What’s next?

We’re incredibly excited about some of the improvements to both localization and our broader developer integrations to launch in the coming months. A few these features include pluralization/variable support in variants, additional SDKs and file formats, and customized string key formats.

💪 Getting Started

To get started using Ditto to set up a single source of truth for your team’s product copy, just try out our web-app or Figma plugin.

For more information, you can always check out our developer documentation or our product help guides.


Update: Since this post was published, Crowdin and Lokalise have both released integrations with Ditto! You can learn more about the Crowdin integration here and the Lokalise integration here.

Success! 🥳 Look forward to Ditto updates in your inbox.
Oh no — something went wrong while submitting the form. Please try again!