Output Directory

The CLI outputs data from Ditto by writing files to disk. By default, these files are written to a ./ditto  folder relative to the current working directory, but the location of the output files can be customized by defining the outDir property in your config.yml file or by setting the environment variable DITTO_OUT_DIR.

./ditto Directory

This directory houses the configuration file (./ditto/config.yml) used by the CLI and is also the default write destination for any output files the CLI writes to disk. It can be overwritten using the --config flag or by setting the environment variable DITTO_PROJECT_CONFIG_FILE . If you run the CLI and the resolved config file does not exist, the CLI will automatically create a default config.yml file at the path specified.

String File Naming Conventions

All string files created will generally adhere to the following template:
{project_id}__{variant_id}.{extension}
  • project_id: the Developer ID of the project.
  • variant_id: the Developer ID of a variant or base for files generated for non-variant text
  • extension: the file extension that corresponds to the configured format(s)
To keep cross-platform behavior consistent, file names will be fully lowercase, have whitespace replaced with hyphens, and have non-word characters (with the exception of - and _) removed.

Format-specific Files

JSON

If one or more JSON string formats are configured, a series of json files will be generated, on a project-variant pair basis. Generally each file will follow the shown format:
{
	"text-item-developer-id": "string with {{variableId}} variables escaped",
	...,
	"welcome": "Hello {{userFirstName}}!"
}
Additionally, a variables.json file will be generated that contains information about any variables used within the fetched projects. The file has the following format:
{
  "text-variable-id": {
    "example": "example_value",
    "fallback": "default_value"
  },
  "number-variable-id": {
    "example": "1",
    "fallback": "10"
  },
  "link-variable-id": {
		 "text": "URL display text",
	    "url": "https://dittowords.com"
  },
  "list-variable-id": [
	  "value1",
	  "value2",
	  "value3"
  ],
  "map-variable-id": {
    "key1": "value1",
    "key2": "value2",
    "key3": "value3"
  },
}

Framework-specific Files

Within each output format, an optional framework can be provided. The framework generates additional helper files to assist with using the output strings files with common third party libraries. Currently only i18next is supported.

i18next

Formats supported: JSON Supported Properties:

type: “commonjs” | “module” (default “commonjs”)

By default, additional javascript files will be generated using commonjs syntax. This property configures the output to us commonjs or module syntax in the generated files. Details: Generates an additional javascript file that imports the generated strings files, and exports an object with the json strings grouped by their variants.
// CommonJS
const exampleProject1Base = require("./example-project-1__root__base.json");
const exampleProject1Spanish = require("./example-project-1__root__spanish.json");
const exampleProject2Base = require("./example-project-2__base.json");
const exampleProject2Spanish = require("./example-project-2__spanish.json");

module.exports = {
  base: {
	  ...exampleProject1Base,
	  ...exampleProject2Base
  },
  spanish: {
	  ...exampleProject1Spanish,
	  ...exampleProject2Spanish
  },
};

// ESM
import exampleProject1Base from "./example-project-1__root__base.json";
import exampleProject1Spanish from "./example-project-1__root__spanish.json";
import exampleProject2Base from "./example-project-2__base.json";
import exampleProject2Spanish from "./example-project-2__spanish.json";

export default {
  base: {
	  ...exampleProject1Base,
	  ...exampleProject2Base
  },
  spanish: {
	  ...exampleProject1Spanish,
	  ...exampleProject2Spanish
  },
};