Importing String Files

To quickly integrate strings from your codebase into Ditto, you can use our JSON import feature to create components in your component library. Using our JSON import, you'll be able to:

• Quickly create components from text currently being used in production
• Sync and manage text currently in development without Figma files

This Help Guide will go over how our JSON imports work.

‍

Basics

To import a JSON file of strings into your component library, click the "+ New Component" button at the top right of your component library and select the "Import as JSON" option.

‍

👉 Quick note: To access the import functionality, you'll need to have Developer Mode turned on for the Component Library. Learn more about Developer Mode ->

Supported Formats

We currently support 3 JSON formats: flat, nested, and structured. In each of the three formats, the component's name will be generated from the keys used in the JSON.

Notably, the default format that is selected when exporting from the component library — Full Component Library JSON — is not supported as an import format.

Flat JSON

Example:

{
	"mobile.onboarding.header":"Welcome!",
	"mobile.onboarding.cta": "Sign Up",
	"mobile.disclaimer": "Return to sender"
}

Resulting components:

In the flat format, any periods (.) in the key name will be converted into forward slashes (/) in the component name to organize components in the component library. The component's API ID will remain the same as the key.

‍

Nested JSON

Example:

{
	"mobile": {
		"onboarding": {
			"header": "Welcome!",
			"cta": "Sign Up"
		},
		"disclaimer": "Return to sender"
	}
}

Resulting components:

In the nested format, key nesting will be converted into forward slashes (/) in the component name to organize components in the component library.

‍

Structured JSON

Example:

{
	"mobile.onboarding.header": {
		"text": "Welcome!",
		"notes": "modal header for onboarding funnel"
	},
	"mobile.onboarding.cta": {
		"text": "Sign Up",
		"tags": ["button", "cta"]
	},
	"mobile.disclaimer": {
		"text": "Return to sender"
	}
}

Properties that get can parsed from the structured JSON format:

Resulting components:

In the structured format, like in the flat format, any periods (.) in the key name will be converted into forward slashes (/) in the component name to organize components in the component library.

‍

Android XML

Example:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
  <string name="mobile.onboarding.header">
    Welcome!
  </string>
  <string name="mobile.onboarding.cta">
    Sign Up
  </string>
  <string name="mobile.disclaimer">
    Return to sender
  </string>
</resources>

Resulting components:

‍

iOS .strings

Example:

"mobile.onboarding.header" = "Welcome!";
"mobile.onboarding.cta" = "Sign Up";
"mobile.disclaimer" = "Return to sender";

Resulting components:

Have a file format that you'd like to have supported? Let us know!

‍

Importing a file as a Variant

If all the keys in an imported file match the API IDs of existing components, no new components will be created; instead, the strings in the file will be applied to existing components as a variant.

When importing a file as a variant, text in the JSON file will be matched to components in the component library based on their API ID.