> For the complete documentation index, see [llms.txt](https://developer.frontitude.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.frontitude.com/developer-cli/configuration-file.md).

# Configuration file

## Overview

The Frontitude CLI uses a local configuration file called `frontituderc.json` to determine which text sources to pull from your Frontitude workspace and where to write the output.

> **Note:** This file is managed by the Frontitude CLI. While you can edit it manually, it's recommended to run `frontitude init`, or `frontitude source set` if you’ve already completed `init`, to updated it.

## File location

`frontituderc.json` is created at the root of your project directory. It is safe — and recommended — to commit this file to version control so that your team shares the same CLI configuration.

## Properties

| Property              | Type                | Required             | Description                                                                             |
| --------------------- | ------------------- | -------------------- | --------------------------------------------------------------------------------------- |
| `filePath`            | `string` or `array` | Yes                  | Relative path to the output strings file, or patterns with `{prefix}`.                  |
| `library`             | `boolean`           | No                   | Whether to include texts from the Copy Library.                                         |
| `projects`            | `array`             | No                   | Frontitude projects to pull texts from.                                                 |
| `folders`             | `array`             | No                   | Frontitude workspace folders to pull texts from.                                        |
| `xliffVersion`        | `string`            | No                   | XLIFF version when using `.xlf` / `.xliff` output.                                      |
| `variableFormat`      | `string`            | No                   | Variable syntax of a `.json` strings file. Defaults to `{{name}}`.                      |
| `pluralFormat`        | `object`            | No                   | Plural style of a `.json` strings file. Defaults to `suffix` with `_`.                  |
| `newFilePath`         | `string`            | No                   | Where `pull` creates the file of a new key prefix. Only with `{prefix}`.                |
| `fallbackFilePath`    | `string`            | Yes, with `{prefix}` | The file for keys that cannot go to a prefix file.                                      |
| `tags`                | `array` or `string` | No                   | Default tags for `pull --tags` and `push --tag`.                                        |
| `update`              | `boolean`           | No                   | Whether `push` also updates existing keys. Defaults to `false`.                         |
| `onConflict`          | `string`            | No                   | What `push --update` does with a conflict in a run that cannot ask. Defaults to `skip`. |
| `status`              | `string`            | No                   | Status for the components that `push` creates or updates.                               |
| `includeTranslations` | `boolean`           | No                   | Whether `push --update` also pushes translation files. Defaults to `false`.             |

> At least one text source (`library`, `projects`, or `folders`) must be configured for `frontitude pull` to work.

#### `filePath`

**Type:** `string`, or `array` of `string` when you use `{prefix}`

The relative path where the CLI writes the pulled texts (e.g. `./strings.json`). The file extension determines the output format:

| Extension  | Format        |
| ---------- | ------------- |
| `.json`    | JSON          |
| `.xml`     | Android XML   |
| `.xlf`     | XLIFF         |
| `.xliff`   | XLIFF         |
| `.strings` | Apple Strings |

To write one file for each key prefix, put `{prefix}` in the file name. See [One file per key prefix](#one-file-per-key-prefix).

**Default:** `./strings.json`

#### `library`

**Type:** `boolean`

Set to `true` to include texts from your workspace's Copy Library as a source. When `false` or omitted, the Copy Library is not included.

#### `projects`

**Type:** `Array<{ name: string, id: string }>`

A list of Frontitude projects to pull texts from. Each entry contains:

* `name` — The display name of the project. Stored for readability so you can identify entries without looking up UUIDs. Not sent to the API.
* `id` — The unique project identifier used by the CLI to fetch texts.

These values are populated automatically by `frontitude init` or `frontitude source set` — you should not need to look up or edit IDs manually. If a project is renamed in Frontitude, the `name` in the config will be stale until you re-run `frontitude source set`.

#### `folders`

**Type:** `Array<{ name: string, id: string }>`

A list of workspace folders to pull texts from. When a folder is selected, all projects inside that folder are included at pull time. Each entry contains:

* `name` — The display name of the folder. Stored for readability only and not sent to the API.
* `id` — The unique folder identifier used by the CLI to resolve projects at pull time.

As with projects, if a folder is renamed in Frontitude the `name` here will be stale until you re-run `frontitude source set`.

#### `xliffVersion`

**Type:** `string` — `"1.2"` or `"2.0"`

Only relevant when `filePath` uses a `.xlf` or `.xliff` extension. Specifies which version of the XLIFF standard to use for the output file. Defaults to `"1.2"` if not set.

#### `variableFormat`

{% hint style="info" %}
Available from CLI version 2.0.0 and above.
{% endhint %}

**Type:** `string`

The variable syntax of your `.json` strings file. It is a template that contains the word `name` exactly once. `pull` writes variables in this syntax, and `push` reads them back.

| Template    | Variable `first_name` is written as |
| ----------- | ----------------------------------- |
| `{{name}}`  | `{{first_name}}` (default)          |
| `{name}`    | `{first_name}`                      |
| `%{name}`   | `%{first_name}`                     |
| `${name}`   | `${first_name}`                     |
| `%name%`    | `%first_name%`                      |
| `:name`     | `:first_name`                       |
| `{ $name }` | `{ $first_name }`                   |

The `--variable-format` flag overrides it. See [Variable and plural formats](/developer-cli/file-formats/web--json.md#variable-and-plural-formats) for examples and limitations.

`frontitude init` sets it for an existing `.json` file when `{name}`, `%{name}`, or `${name}` appears at least twice as often as any other syntax. If no syntax wins, `init` tells you how to set it by hand. `init` never writes the default `{{name}}`, and it doesn't detect plural styles.

**Default:** `{{name}}`

#### `pluralFormat`

{% hint style="info" %}
Available from CLI version 2.0.0 and above.
{% endhint %}

**Type:** `object`

How your `.json` strings file stores plurals.

| Property    | Type                | Required           | Description                                                                                                                  |
| ----------- | ------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `style`     | `string`            | Yes                | `suffix` or `joined`.                                                                                                        |
| `separator` | `string`            | No, `suffix` only  | Text between the key and the plural form. Defaults to `_`.                                                                   |
| `delimiter` | `string`            | Yes, `joined` only | Text between the forms inside one value, for example `" \|\|\|\| "`.                                                         |
| `forms`     | `array` of `string` | No, `joined` only  | The forms in the order they appear in the value, for example `["one", "other"]`. Defaults to the plural forms of the locale. |

The `--plural-format` flag overrides `style`. The other properties come from the config file, and only when its `style` matches the flag. So `--plural-format joined` fails without a joined `delimiter` in the config ([`INVALID_FORMAT_CONFIG`](/developer-cli/errors.md#variable-and-plural-format-errors)). See [Variable and plural formats](/developer-cli/file-formats/web--json.md#variable-and-plural-formats) for examples and limitations.

**Default:** `{ "style": "suffix", "separator": "_" }`

## One file per key prefix

{% hint style="info" %}
Available from CLI version 2.0.0 and above.
{% endhint %}

These keys set up one strings file for each key prefix. See [One file per key prefix](/developer-cli/file-formats/web--json.md#one-file-per-key-prefix) for how `pull` and `push` use the files.

Without `{prefix}` in `filePath`, the CLI works as before. `tags` still works. `newFilePath` and `fallbackFilePath` are ignored, with a warning.

#### `filePath` patterns

**Type:** `string` or `array` of `string`

| Part       | Rule                                                                                                                                   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Location   | Relative to the folder of `frontituderc.json`, with `/` on every system. No leading `/`, no drive letter, no `..`.                     |
| File name  | Ends with `.json`.                                                                                                                     |
| `{prefix}` | Required, once, in the file name. Text can come before and after it, as in `{prefix}.strings.json`. It matches one or more characters. |
| `{locale}` | Optional. A Frontitude locale id. See [Translations](/developer-cli/file-formats/web--json.md#translation-files).                      |
| `*`        | Any text inside one folder name, or no text. Not in the same name as `{prefix}` or `{locale}`.                                         |
| `**`       | Any number of folders, or none. Must be a whole folder name, and not the file name.                                                    |

For example, `./src/**/strings/{prefix}.json` finds both `src/pages/strings/Checkout.json` and `src/components/strings/Banner.json`. `./src/strings/{prefix}-*.json` is not valid, because `*` and `{prefix}` are in the same name.

* `*` and `**` skip `node_modules`, `.git`, folders whose name starts with a dot, and symbolic links to folders. To include such a folder, write its name, for example `./.storybook/strings/{prefix}.json`. Symbolic links to files, and to folders that a pattern names directly, are followed.
* In a list, every pattern must contain `{prefix}`. A file that matches two patterns belongs to the first one. Use `{locale}` in every pattern of a list, or in none.
* A folder that does not exist matches no files. This is not an error.
* Letter case must match: `{prefix}.json` does not find `Checkout.JSON`.
* Keep patterns narrow. Don't use `./**/{prefix}.json`: it matches every JSON file in the project, such as settings files. Use a strings folder, such as `./src/**/strings/{prefix}.json`, or a name ending, such as `{prefix}.strings.json`.

#### `newFilePath`

**Type:** `string`

Where `pull` creates the file for a key prefix that has no file yet. It needs `{prefix}` once in the file name, and no `*` or `**`. It has `{locale}` only when `filePath` has it. The files it creates must match a `filePath` pattern, or the next `pull` and `push` would not find them.

#### `fallbackFilePath`

**Type:** `string`

Required with `{prefix}`. One `.json` path, without `*`, `**`, or `{prefix}`, that no `filePath` pattern matches. It has `{locale}` only when `filePath` has it. `pull` creates it the first time a key goes there, and `push` reads it with the prefix files. It receives the keys:

* that have no prefix, or a prefix that cannot be a file name
* of a new prefix, when `newFilePath` is not set
* of a prefix that differs only in letter case from an existing file
* of a prefix whose file would be a file that the CLI skips

#### `tags`

**Type:** `array` of `string`, or a comma-separated `string`

For example, `["admin-console"]` or `"admin-console, web"`. Works with or without `{prefix}`.

* `pull` uses it as the default for [`--tags`](/developer-cli/commands.md#pull).
* `push` uses it as the default for [`--tag`](/developer-cli/commands.md#push).
* A non-empty flag replaces `tags`. An empty flag counts as not set.

Any other shape, such as a number, stops the command before any request. See [`INVALID_TAGS_CONFIG`](/developer-cli/errors.md#multi-file-output-errors).

## Update existing keys

{% hint style="info" %}
Available from CLI version 2.0.0 and above.
{% endhint %}

These keys set the defaults for `push --update`, and a flag overrides them. See [Update existing keys](/developer-cli/commands.md#update-existing-keys) for how update works. A value of the wrong type, or one that is not in its list, stops `push` before any request ([`INVALID_PUSH_CONFIG`](/developer-cli/errors.md#update-errors)).

```json
{
  "filePath": "./src/strings.json",
  "library": true,
  "update": true,
  "onConflict": "fail",
  "includeTranslations": true
}
```

#### `update`

**Type:** `boolean`

Set to `true` to make `push` also update the keys that you changed in code. `--update` and `--no-update` override it. With `true`, `pull` also writes a lock file next to each strings file. See [Lock files](/developer-cli/commands.md#lock-files).

**Default:** `false`

#### `onConflict`

**Type:** `string` — `"skip"`, `"overwrite"` or `"fail"`

What `push --update` does with a conflict in a run that cannot ask, such as CI. `--on-conflict` overrides it. A create-only push ignores it. See [Conflicts](/developer-cli/commands.md#conflicts).

**Default:** `"skip"`

#### `status`

**Type:** `string` — `"new"`, `"draft"`, `"review"` or `"final"`

The status for the components that `push` creates or updates. `--status` overrides it. See [How update works](/developer-cli/commands.md#how-update-works) for what `final` does.

#### `includeTranslations`

**Type:** `boolean`

Set to `true` to make `push --update` also push the translation files that `pull --include-translations` writes. A create-only push ignores it. `--include-translations` overrides it. See [Translations on push](/developer-cli/commands.md#translations-on-push).

**Default:** `false`

## Examples

#### Full example

```json
{
  "filePath": "./locales/strings.json",
  "library": true,
  "projects": [
    {
      "name": "Authentication feature",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ],
  "folders": [
    {
      "name": "Mobile",
      "id": "79a64273-69c3-40bb-8a6a-5e405981707c"
    }
  ]
}
```

#### Minimal example

```json
{
  "filePath": "./strings.json",
  "library": false,
  "projects": [
    {
      "name": "My Project",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}
```

#### XLIFF output

```json
{
  "filePath": "./translations/strings.xlf",
  "xliffVersion": "1.2",
  "library": false,
  "projects": [
    {
      "name": "My Project",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}
```

#### Custom variable and plural formats

```json
{
  "filePath": "./locales/strings.json",
  "variableFormat": "%{name}",
  "pluralFormat": { "style": "joined", "delimiter": " |||| " },
  "library": true
}
```

#### One folder of page files

```
src/strings/
  Checkout.json
  Profile.json
```

```json
{
  "library": true,
  "filePath": "./src/strings/{prefix}.json",
  "newFilePath": "./src/strings/{prefix}.json",
  "fallbackFilePath": "./src/strings-fallback.json",
  "tags": ["admin-console"]
}
```

`Checkout.heading` goes to `src/strings/Checkout.json`. A new prefix, such as `Wishlist.title`, creates `src/strings/Wishlist.json`. A key without a prefix, such as `heading`, goes to `src/strings-fallback.json`.

#### Strings folders at different depths

```
src/
  pages/strings/Checkout.json
  components/strings/Banner.json
```

```json
{
  "library": true,
  "filePath": "./src/**/strings/{prefix}.json",
  "newFilePath": "./src/pages/strings/{prefix}.json",
  "fallbackFilePath": "./src/strings-fallback.json"
}
```

`Banner.label` goes to `src/components/strings/Banner.json`. A new prefix gets a file in `src/pages/strings`. The same setup as a list:

```json
{
  "filePath": [
    "./src/pages/strings/{prefix}.json",
    "./src/components/strings/{prefix}.json"
  ],
  "newFilePath": "./src/pages/strings/{prefix}.json",
  "fallbackFilePath": "./src/strings-fallback.json"
}
```

## How it's generated

Running `frontitude init` walks you through an interactive setup:

1. **Select sources:** pick which projects, folders, or the Copy Library to pull texts from.
2. **Set output path:** choose the file path and format for the pulled strings.

The CLI writes your selections to `frontituderc.json`. To update your sources later without re-running the full init flow, use `frontitude source set`.

`init` cannot create a `{prefix}` setup, and refuses a path with `{prefix}` at the file path prompt. Write `filePath` and `fallbackFilePath` by hand. If `filePath` already uses `{prefix}`, `init` keeps it, asks only for your sources, and prints `filePath uses {prefix}; edit frontituderc.json to change routing.` It detects the variable syntax in the matching files and the fallback file. It doesn't write `newFilePath`, `fallbackFilePath`, or `tags`. If these settings are not valid, `init` stops with the error before it asks anything.

## Working with multiple config files

{% hint style="info" %}
Available from CLI version 1.4.0 and above.
{% endhint %}

By default the CLI reads `frontituderc.json` from the directory you run it in. The `--config <path>` flag points it at a different config file instead. The path can be absolute or relative, and the flag works on every command (`pull`, `push`, `init`, and so on).

Relative `filePath` values inside the config file are resolved against that file's own directory, so `--config` behaves exactly as if you had changed into that directory before running the CLI. Each invocation uses exactly one config file; to drive several, run the CLI once per file and let an npm script handle the orchestration.

### Monorepo: one install, many packages

Install the CLI once at the repository root and give each package its own config file (`packages/<name>/frontituderc.json`). A root npm script can then pull or push every package in one command:

```json
{
  "scripts": {
    "i18n:pull:web": "frontitude pull --config packages/web/frontituderc.json",
    "i18n:pull:mobile": "frontitude pull --config packages/mobile/frontituderc.json",
    "i18n:pull:admin": "frontitude pull --config packages/admin/frontituderc.json",
    "i18n:pull": "npm run i18n:pull:web && npm run i18n:pull:mobile && npm run i18n:pull:admin"
  }
}
```

A package with one strings file per key prefix needs only one config file. See [One file per key prefix](#one-file-per-key-prefix).

### Multiple config profiles in one project

The same mechanism lets a single project keep several strings files side by side — for example a workspace-level Copy Library alongside a project-scoped file, or one file per project. Create a config file per profile and point `--config` at each in turn:

```json
{
  "scripts": {
    "i18n:pull:library": "frontitude pull --config frontituderc.library.json",
    "i18n:pull:app": "frontitude pull --config frontituderc.app.json",
    "i18n:pull": "npm run i18n:pull:library && npm run i18n:pull:app"
  }
}
```

Config files in the same directory are fully independent — they can target different projects, the Copy Library, or different output files without interfering with each other.

> **Note:** To create a new config file at a specific path, run `frontitude init --config path/to/frontituderc.json`.
