> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> The file structure of text pulled down via the CLI

## 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 setting the environment variable `DITTO_TEXT_DIR`.

If a `DITTO_TEXT_DIR` environment variable is specified, the config will still be read from a `./ditto` folder relative to the current working directory that the CLI is executing in.

## `./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.

If you run the CLI in a directory that does not contain a `ditto/` folder, the folder and a default `config.yml` file will be automatically created.

## String File Naming Conventions

All string files created will adhere to the following template:

```
{source_name}__{variant_name}.{extension}
```

* `source_name`: the name of the source a given file holds data for
  * for components, this is `components__{folder_name}`
  * for projects, this is `{project-name}`
* `variant_name`: the API 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.

See the section on [iOS format-specific files](#iOS) for the only exception to these conventions.

## Format-specific Files

### JSON

If one or more JSON string formats are configured, an `index.js` driver file is generated to simplify the process of integrating Ditto into JavaScript apps.

If a `package.json` file is detected with `"type": "module"`, the driver file will be generated as an ESM module. Otherwise, it will be generated as a CommonJS module.

```js theme={null}
// CommonJS
const componentsRootBase = require("./components__root__base.json");
const componentsRootSpanish = require("./components__root__spanish.json");
const exampleProjectBase = require("./example-project__base.json");
const exampleProjectSpanish = require("./example-project__spanish.json");

module.exports = {
  ditto_component_library: {
    base: { ...componentsRootBase },
    spanish: { ...componentsRootSpanish },
  },
  project_xxx: {
    base: { ...exampleProjectBase },
    spanish: { ...exampleProjectSpanish },
  },
};

// ESM
import componentsRootBase from "./components__root__base.json";
import componentsRootSpanish from "./components__root__spanish.json";
import exampleProjectBase from "./example-project__base.json";
import exampleProjectSpanish from "./example-project__spanish.json";

export default {
  ditto_component_library: {
    base: { ...componentsRootBase },
    spanish: { ...componentsRootSpanish },
  },
  project_xxx: {
    base: { ...exampleProjectBase },
    spanish: { ...exampleProjectSpanish },
  },
};
```

To enable easy Typescript compatibility, an `index.d.ts` file is also generated with type definitions for the driver file.

The generation of both the `index.js` and `index.d.ts` files can be disabled by specifying `disableJsDriver: true` in your `config.yml` file.

### iOS

If one or more iOS string formats (`ios-strings`, `ios-stringsdict`) are configured alongside the [iosLocales](/cli-reference/configuration#ioslocales) property, iOS string files are grouped into localization bundles and a `Ditto.swift` driver file is generated.

The string files will be structured as follows:

```sh theme={null}
ditto/
├── en.lproj/
│   ├── components.strings
│   ├── project1.strings
├── es.lproj/
│   ├── components.strings
│   ├── project1.strings
```

The `Ditto.swift` driver file will look like this:

```swift theme={null}
//
// Ditto.swift
//
// Created by the Ditto CLI on 10/6/2023, 1:16:52 PM
//

import SwiftUI

struct Ditto {
  public static func component1(_ localeOverride: String? = nil) -> String {
    String.localizedStringWithFormat(NSLocalizedString("component-1", tableName: "components", /* ... */))
  }

  public struct project1 {
    public static func textItem1(_ localeOverride: String? = nil, variable1: String) -> String {
      String.localizedStringWithFormat(NSLocalizedString("text-item-1", tableName: "project1", /* ... */), variable1)
    }
  }
```

These files are designed to be imported into Xcode **by reference**. This enables using the CLI to pull the latest strings from Ditto and have the text in your project automatically updated.

To add these files to your Xcode project:

1. Open Finder and select all `.strings` and `.stringsdict` files inside of the respective `lproj` folders.
2. Drag the selected files into your Xcode project.
3. When prompted, select **Create folder references** and deselect **Copy if needed**.
4. Click **Finish**.

Once all your localization bundles and `Ditto.swift` driver are imported into Xcode, you can call methods from the `Ditto` struct directly to get localized strings:

```swift theme={null}
struct ContentView: View {
  var body: some View {
    Text(Ditto.component1())
    Text(Ditto.textItem1(variable1: "Hello world!"))
  }
}
```