Quickstart
Get set up to sync product text in just a few minutes
Authenticating
Time Estimate: 2 minutes
Enable developer integrations
To start using Ditto’s developer integrations, you’ll need to enable developer integrations for your workspace on the developer integrations page. If the developer integrations add-on isn’t a part of your current plan, you can enable a 2-week trial.
Generate an API key
This will allow you fetch text from Ditto via our API or CLI. Remember to store this key safely!
Setting up the sample project
Time Estimate: 10 minutes
In each Ditto workspace, there is a sample project (✍️ DittoPay Signup Flow) that demonstrates what Ditto usage might look like, with sample comments, metadata, components, and a sample Figma file to connect to.
To quickly test drive Ditto’s developer integrations, you can connect the sample project in your workspace to a frontend using one of our example apps. This is helpful for understanding:
- How Ditto keeps text in sync from design to development (using our CLI)
- How components in Ditto work (and integrate with a project)
- How Ditto’s developer integrations work for React, iOS, or Android
- How to utilize Ditto variants, plurals, and variable interpolation
Instructions:
Navigate to the sample project
This project (and its corresponding components) should be in every workspace.
Clone one of the sample repos.
Sample repos can be found here for several frameworks. Choose the one most similar to the framework you usually work with!
The repo is already set up with a pre-configured CLI and the text files with developer IDs from the sample components in your workspace.
Run the app and install the CLI
Follow the repo’s README to run the app and install the pre-configured CLI — this shouldn’t take more than a few minutes!
The first time you run the Ditto CLI, you’ll be asked to provide an API key.
That's it! 🎉
Afterwards, you’re all set up. Run the CLI to fetch down the latest changes from Ditto.
You can also try making an edit in Ditto and then pulling in the latest updates to your string files via the CLI.
Setting up Ditto in your own repository
Now that you’ve built an understanding of how Ditto works, you can set up Ditto to manage your own team’s strings.
Don’t worry — you don’t have to do this all at once. Especially for teams with large and complex codebases, it’s always an option to have Ditto manage the text for a specific product area and expanding coverage over time.
We’ll describe setup solutions depending on how you currently manage strings in your code-base.
- Option 1: If you currently manage text via string files of any kind (JSON, iOS, XML, etc.). If you currently localize your text or build for mobile (iOS, Android), you fall in this category.
- Option 2: If you currently manage hardcoded text.
If you have a mix of both in your code base, we’d recommend starting with Option 1.
Option 1: If you currently manage string files
Import your string file(s) to your Ditto component library
Head to your component library and import your string file. The import will preserve all of your existing string keys from the file — meaning you can immediately start using Ditto to fetch and update your string files with minimal adjustment to your code base. For more information on importing strings, check out this guide. Have a string file format we don’t yet support? Let us know!
Install the Ditto CLI in your repository
Instructions for installing and setting up the CLI can be found here.
Configure CLI to fetch the imported components
You can specify the components and the string file format(s) in the CLI config.
Update file routes
With the strings now pulled down via the CLI, you can update the existing routes to string files to the new file paths.
And you’re done! 🎉 You now have the strings from your code base synced to Ditto.
Option 2: If you currently hard code strings
If you currently have strings hardcoded in your repository, you’ll have to decouple them into string files in order to have Ditto manage updates to strings.
In addition to being easier to maintain, decoupling your content and code makes it easier to scale — meaning minimal future work required to localize or A/B test. If it’s easier, you can also start with an initial product area and expand the amount of decoupling content over time to increase the surface area of text managed by Ditto.
Create components for strings
You can do this in a couple of different ways, depending on which is the best current source of truth for your team’s product text.
Install the Ditto CLI in your repository
Instructions for installing and setting up the CLI can be found here.
Fetch your component library down locally as string files
You can specify the components and the string file format(s) in the CLI config.
Replace hardcoded text with developer IDs
From the string and IDs pulled down via the CLI, replace the hardcoded text with the developer IDs to connect the two. To streamline this process: - Use an SDK like our React SDK or another framework-specific SDK to surface the text associated with the IDs in the string files. - Use our VS Code Extension to insert string keys directly from your IDE based on matching text. - Use our Figma plugin to quickly surface and copy over the Ditto developer IDs of selected text in Figma. You can also open our Figma plugin in Figma Dev Mode, which will surface IDs in addition to framework-specific code snippets.
To make help surface the text associated with IDs, we recommend checking out our available SDKs or an internationalization framework like i18next.
Building a Robust Workflow
With the basics set up, you also can extend to be more powerful in your team’s workflow:
- Connecting components to design files — this keeps text in sync from design to development. You can do this in a few seconds with component attach suggestions!
- Have Ditto handle more aspects of your development process — whether it’s the updating of keys or opening of pull requests, you can extend functionality by using our webhooks, GitHub Action, VSCode Extension, and more.