Skip to main content

​
Overview

The config.yml file is the source of truth for a given directory about how the CLI should fetch and store data from Ditto based on the specified properties. It includes information about which Ditto components the CLI should pull text from, the string file formats, and more. This is the default configuration file that is generated the first time that the CLI is run in a given directory: 
sources:
  components:
    enabled: true
format: flat
variants: true

​
Supported Properties

Listed below are each of the properties that you can specify in your CLI config.

​
sources

A list of places the CLI should pull text data from. For the CLI to function, at least one source type (components or projects) is required.

​
sources.components

A boolean or configuration object indicating how component data should be pulled from your component library. The simplest configuration is a boolean, which indicates that all components in your component library should be fetched: 
sources:
  components: true
You can also pass an object that supports two complementary properties: root and folders.
  • root controls behavior for components that are NOT in folders (i.e. that are at the root of the component library)
  • folders controls behavior for components that are ARE in folders
Further examples on how to use the two properties to specify the components fetched:
If root is true and folders is unspecified, only components not in folders will be fetched:
sources:
  components:
    root: true
If root is false and folders is unspecified, only components in any folder will be fetched:
sources:
  components:
    root: false
If root is unspecified and folders contains a list of component folders, only components in the specified folders will be fetched:
sources:
  components:
    folders:
      - id: folder-api-id-1
        name: Folder 1
      - id: folder-api-id-2
        name: Folder 2
If root is true and folders contains a list of component folders, non-folder components and components in the specified folders will be fetched:
sources:
  components:
    root: true
    folders:
      - id: folder-api-id-1
        name: Folder 1
      - id: folder-api-id-2
        name: Folder 2
root can also be specified as a configuration object with a status property to indicate that non-folder components should be fetched that have the indicated status:
sources:
  components:
    root:
      status: WIP

​
sources.projects

A list of projects to pull text from. 
sources:
  projects:
    - id: 61b8d26105f8f400e97fdd14
      name: Landing Page Copy
    - id: 606cb89ac55041013d552f8b
      name: User Settings
  • The name property is used for display purposes when referencing a project in the CLI, but does not have to be an exact match with the project name in Ditto.
An exclude_components property can be added on a per-project basis to indicate that text items should only be pulled which are not associated with a component: 
sources:
  projects:
    - id: 61b8d26105f8f400e97fdd14
      name: Landing Page Copy
      exclude_components: true

​
variants

Enables including variant information when pulling text data for configured sources. Defaults to false if not specified. 
variants: true

​
format

The format that text data should be generated in. For examples of each format, see JSON, iOS Strings, and Android XML in the String Formats documentation. Accepted values:
  • structured
  • flat
  • nested
  • android
  • ios-strings
  • ios-stringsdict
Defaults to flat if not specified. 
format: flat
Also accepts a list of values: 
format:
  - ios-strings
  - ios-stringsdict
You should not specify multiple JSON formats in the same configuration, as they will overwrite one another when writing to disk.

​
status

If specified, only source data with the indicated status will be fetched. Accepted values:
  • NONE
  • WIP
  • REVIEW
  • FINAL
If status is specified at the top level of the configuration, it will apply to all sources: 
status: FINAL
sources:
  components: true
  projects:
    - id: project-1
      name: Project 1
status can also be specified at the level of individual sources: 
sources:
  components:
    root:
      status: REVIEW
    folders:
      - id: folder-api-id-1
        name: Folder 1
        status: NONE
  projects:
    - id: project-1
      name: Project 1
      status: WIP
If both are specified, a source-level status overrides a top-level status. More information about Ditto statuses can be found here.

​
richText

If defined with the flat format, output values will be HTML strings (rich text) for each piece of source data. If defined with the structured format, output data will include a rich_text property that is an HTML string (rich text) for each piece of source data. You can read more about Ditto’s rich text feature here. 
richText: true

​
iosLocales

A property that maps variant IDs in Ditto to iOS locale IDs, intended to simplify the process of integrating Ditto with an iOS project. This property should only be defined in conjunction with one or both of the ios-strings or ios-stringsdict formats. When this property is defined, iOS string files written to disk by the CLI are grouped into lproj localization bundles, and a Ditto.swift driver file is generated. 
iosLocales:
  - base: en
  - spanish: es
The base property is required, and should map to the locale ID corresponding to the default language of your iOS project. See iOS format-specific files for more information.

​
disableJsDriver

A boolean property that disables the generation of the index.js and index.d.ts driver files when working with JSON formats. 
disableJsDriver: true

​
Full Configuration Example

sources:
  components:
    root: true
    folders:
      - id: onboarding
        name: Onboarding
      - id: onboarding-2
        name: Onboarding 2
        status: WIP
  projects:
    - name: Landing Page Copy
      id: 61b8d26105f8f400e97fdd14
    - name: User Settings
      id: 606cb89ac55041013d552f8b
      status: WIP
variants: true
format: structured
status: FINAL
richText: false
disableJsDriver: false