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

# gleef init

> Initialize Gleef in your project by detecting locale files and creating configuration

The `gleef init` command sets up Gleef in your project by guiding you through the configuration process and creating the necessary configuration file.

## Usage

```bash theme={null}
gleef init
```

## What it does

The `init` command performs several important setup tasks:

1. **Prompts for locale file patterns** using placeholder syntax (e.g., `{locale}`, `{feature}`)
2. **Validates your file patterns** by attempting to load locale files
3. **Fetches company locales** from your Gleef account
4. **Maps file/folder names** to company locales when needed
5. **Creates configuration** in `.gleef/config.json` with proper format options
6. **Sets up custom locale mappings** when file names don't match standard locale codes

## Placeholder Patterns

The command uses placeholder syntax to define file patterns:

* `{locale}` - **Required placeholder** for the locale identifier
* `{feature}` or `{namespace}` - Optional placeholders for organizing translations

### Supported File Formats

Gleef supports these localization file formats:

* `.json` - JSON localization files
* `.xml` - XML localization files
* `.yaml` / `.yml` - YAML localization files
* `.strings` - iOS strings files

### Pattern Examples

| Pattern                               | Matches                                                  | Use Case                   |
| ------------------------------------- | -------------------------------------------------------- | -------------------------- |
| `src/locales/{locale}.json`           | `src/locales/en.json`, `src/locales/fr.json`             | Simple locale files        |
| `public/i18n/{locale}/{feature}.json` | `public/i18n/en/common.json`, `public/i18n/fr/auth.json` | Namespaced translations    |
| `locales/{feature}.{locale}.json`     | `locales/common.en.json`, `locales/auth.fr.json`         | Feature-first organization |

## Interactive Setup Process

### Step 1: Enter Locale File Pattern

```bash theme={null}
$ gleef init

    ___ _     _____ _____ _____ 
  / ___| |   | ____| ____|  ___|
 | |  _| |   |  _| |  _| | |_   
 | |_| | |___| |___| |___|  _|  
  \____|_____|_____|_____|_|    

Welcome to the Gleef configuration assistant
You will need your locale files path to continue, using the {locale} placeholder.

? What's your locale files path? › src/locales/{locale}.json
```

### Step 2: Locale Mapping (if needed)

If your file/folder names don't match your company locales:

```bash theme={null}
? Please assign one of your configured locale to this file/folder: en
  fr-FR
  en-US
  es-ES
❯ Skip
```

### Step 3: Success

```bash theme={null}
✔ One pattern added successfully. You can add more in your config file.
src/locales/{locale}.json
Run `gleef push` to start pushing your translations
To customize nested/flat output per format, edit the formatOptions in .gleef/config.json
```

## Generated Configuration

After running `init`, you'll find a `.gleef/config.json` file in your project:

```json theme={null}
{
  "localeFilePatterns": [
    "src/locales/{locale}.json"
  ],
  "formatOptions": {
    "json": {
      "nested": true
    }
  },
  "customLocaleNames": {
    "fr-FR": "french",
    "de-DE": "german"
  }
}
```

### Configuration Properties

| Property             | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| `localeFilePatterns` | Placeholder patterns matching your localization files using `{locale}` syntax    |
| `formatOptions`      | Output format settings for each file type (auto-detected based on your patterns) |
| `customLocaleNames`  | Maps company locale codes to your file/folder names when they don't match        |

## Configuration Examples by Technology

<CodeGroup>
  ```json React/Next.js theme={null}
  {
    "localeFilePatterns": [
      "public/locales/{locale}.json",
      "src/locales/{locale}/{feature}.json"
    ],
    "formatOptions": {
      "json": {
        "nested": true
      }
    }
  }
  ```

  ```json Vue/Nuxt.js theme={null}
  {
    "localeFilePatterns": [
      "locales/{locale}.json",
      "lang/{locale}/{feature}.json"
    ],
    "formatOptions": {
      "json": {
        "nested": true
      }
    }
  }
  ```

  ```json Angular theme={null}
  {
    "localeFilePatterns": [
      "src/assets/i18n/{locale}.json",
      "src/app/{feature}/i18n/{locale}.json"
    ],
    "formatOptions": {
      "json": {
        "nested": true
      }
    }
  }
  ```

  ```json iOS (Swift) theme={null}
  {
    "localeFilePatterns": [
      "ios/MyApp/{locale}.lproj/*.strings"
    ],
    "customLocaleNames": {
      "en-US": "en",
      "fr-FR": "fr",
      "es-ES": "es"
    }
  }
  ```

  ```json Android theme={null}
  {
    "localeFilePatterns": [
      "android/app/src/main/res/{locale}/*.xml"
    ],
    "formatOptions": {
      "xml": {
        "nested": false
      }
    },
    "customLocaleNames": {
      "en-US": "en",
      "fr-FR": "fr",
      "es-ES": "es"
    }
  }
  ```

  ```json Rails theme={null}
  {
    "localeFilePatterns": [
      "config/locales/{locale}.yml",
      "config/locales/{locale}/{feature}.yml"
    ],
    "formatOptions": {
      "yaml": {
        "nested": true
      }
    }
  }
  ```

  ```json Laravel theme={null}
  {
    "localeFilePatterns": [
      "lang/{locale}.json",
      "resources/lang/{locale}/{feature}.php"
    ],
    "formatOptions": {
      "json": {
        "nested": false
      }
    }
  }
  ```

  ```json Django theme={null}
  {
    "localeFilePatterns": [
      "locale/{locale}/LC_MESSAGES/*.po"
    ],
    "customLocaleNames": {
      "en-US": "en",
      "fr-FR": "fr"
    }
  }
  ```
</CodeGroup>

## Complex Project Structures

### Monorepo with Multiple Apps

<CodeGroup>
  ```json Configuration theme={null}
  {
    "localeFilePatterns": [
      "apps/web/src/locales/{locale}.json",
      "apps/mobile/src/i18n/{locale}.json",
      "packages/shared/locales/{locale}/{feature}.json"
    ],
    "formatOptions": {
      "json": {
        "nested": true
      }
    }
  }
  ```

  ```bash Structure theme={null}
  my-monorepo/
  ├── apps/
  │   ├── web/
  │   │   └── src/locales/
  │   │       ├── en.json
  │   │       └── fr.json
  │   └── mobile/
  │       └── src/i18n/
  │           ├── en.json
  │           └── fr.json
  ├── packages/
  │   └── shared/
  │       └── locales/
  │           ├── en/
  │           │   ├── common.json
  │           │   └── auth.json
  │           └── fr/
  │               ├── common.json
  │               └── auth.json
  └── .gleef/
      └── config.json
  ```
</CodeGroup>

### Legacy Project with Custom Names

<CodeGroup>
  ```json Configuration theme={null}
  {
    "localeFilePatterns": [
      "assets/translations/{locale}.json"
    ],
    "formatOptions": {
      "json": {
        "nested": false
      }
    },
    "customLocaleNames": {
      "en-US": "english",
      "fr-FR": "french",
      "es-ES": "spanish",
      "zh-CN": "chinese-simplified"
    }
  }
  ```

  ```bash Structure theme={null}
  legacy-app/
  ├── assets/
  │   └── translations/
  │       ├── english.json
  │       ├── french.json
  │       ├── spanish.json
  │       └── chinese-simplified.json
  └── .gleef/
      └── config.json
  ```
</CodeGroup>

## Troubleshooting

### Pattern Validation Errors

If the pattern validation fails:

<Warning>
  ⚠ No locale files found with this path
  Please correct your path, check the documentation or contact Gleef for help.
</Warning>

**Common issues:**

1. **Missing `{locale}` placeholder** - All patterns must include `{locale}`
2. **Incorrect file paths** - Verify the files exist at the specified location
3. **Wrong file extensions** - Ensure files use `.json`, `.xml`, `.yaml`, or `.strings`
4. **Path syntax errors** - Use forward slashes `/` in patterns

### Locale Mapping Issues

If your file/folder names don't match company locales:

1. **Use the interactive mapping** - The init command will prompt you to map each unmatched locale
2. **Skip unmapped locales** - Choose "Skip" for locales you don't want to include
3. **Update company locales** - Add missing locales in Gleef Studio if needed

### Manual Configuration

If you need to skip the interactive setup:

```json theme={null}
{
  "localeFilePatterns": [
    "your/custom/{locale}.json"
  ],
  "customLocaleNames": {
    "en-US": "english",
    "fr-FR": "french"
  },
  "formatOptions": {
    "json": {
      "nested": true
    }
  }
}
```

## Best Practices

<Tip>Always use the `{locale}` placeholder in your file patterns for proper locale detection.</Tip>

1. **Use descriptive patterns** - Include folder structure in patterns: `src/i18n/{locale}/{feature}.json`
2. **Test your patterns** - Verify patterns match existing files before running init
3. **Plan for namespaces** - Consider using `{feature}` placeholders for organized translations
4. **Review generated config** - Check `.gleef/config.json` matches your expectations
5. **Commit configuration** - Add `.gleef/config.json` to version control

## Next Steps

After initialization:

<CardGroup cols={2}>
  <Card title="Push Translations" icon="upload" href="/cli/commands/push">
    Send your translation keys to Gleef
  </Card>

  <Card title="Configuration Reference" icon="cog" href="/cli/configuration/config-file">
    Learn about all configuration options and advanced patterns
  </Card>
</CardGroup>