Configuration
Setting what text and formats the CLI pulls down
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:
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