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

# Quick Start

> Get up and running with Gleef CLI in minutes

This guide will walk you through setting up your first translation project with Gleef CLI in just a few minutes.

## Prerequisites

Before starting, make sure you have:

* [Installed Gleef CLI](/cli/getting-started/installation)
* [Authenticated with your API key](/cli/getting-started/installation#authenticate-with-gleef)
* A project with existing localization files (JSON, XML, YAML, or .strings)

## Step-by-Step Setup

<Steps titleSize="h3">
  <Step title="Navigate to your project">
    Open your terminal and navigate to your project directory:

    ```bash theme={null}
    cd /path/to/your/project
    ```
  </Step>

  <Step title="Initialize Gleef">
    Run the initialization command to set up Gleef in your project:

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

    This command will:

    * Prompt you to enter your locale file pattern using `{locale}` placeholder
    * Validate the pattern by loading your existing files
    * Map file/folder names to company locales if needed
    * Create a `.gleef/config.json` configuration file

    ### Common Patterns by Technology

    Here are typical patterns you might enter based on your stack:

    <CodeGroup>
      ```bash React/Next.js theme={null}
      public/locales/{locale}.json
      # or for namespaced:
      src/locales/{locale}/{feature}.json
      ```

      ```bash Vue/Nuxt.js theme={null}
      locales/{locale}.json
      # or for namespaced:
      lang/{locale}/{feature}.json
      ```

      ```bash Angular theme={null}
      src/assets/i18n/{locale}.json
      # or for feature-based:
      src/app/{feature}/i18n/{locale}.json
      ```

      ```bash iOS (Swift) theme={null}
      ios/MyApp/{locale}/{feature}.strings
      ```

      ```bash Android theme={null}
      android/app/src/main/res/{locale}/strings.xml
      ```

      ```bash Rails theme={null}
      config/locales/{locale}.yml
      # or for namespaced:
      config/locales/{locale}/{feature}.yml
      ```

      ```bash Laravel theme={null}
      lang/{locale}.json
      # or for PHP arrays:
      resources/lang/{locale}/{feature}.php
      ```
    </CodeGroup>

    <Info>Always use the `{locale}` placeholder in your pattern - it's required for proper locale detection.</Info>
  </Step>

  <Step title="Complete the setup">
    After entering your pattern and mapping any locales, you'll see output like:

    ```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
    ```

    Check the generated `.gleef/config.json` file to verify the configuration matches your project structure.
  </Step>

  <Step title="Push your first translations">
    Upload your existing translation keys to Gleef:

    ```bash theme={null}
    gleef push --skip-review
    ```

    This will:

    * Analyze your local translation files
    * Send new and modified keys to Gleef
    * Publish all translations without asking your team for review (similar to an initial commit)

    <Note>`gleef push` is the standard command for sending new and updated translations to Gleef. Use `gleef translate` when you want to generate AI translations and merge them back into your local files in one step.</Note>

    You'll see progress output like:

    ```
    Pushing 15 new translations
    ✔ Your translations were pushed successfully.
    ```
  </Step>

  <Step title="Pull translated content">
    After translations are reviewed and approved in Gleef Studio, sync them back:

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

    This updates your local files with the latest approved translations.
  </Step>
</Steps>

## Example Project Structure

Here's an example of how Gleef CLI works with a typical project structure:

```
my-app/
├── src/
│   └── locales/
│       ├── en-US.json
│       ├── fr-FR.json
│       └── es-ES.json
├── .gleef/
│   └── config.json
└── .gitignore
```

**Before initialization:** Only the locale files exist

**After `gleef init`:** Configuration is created

**After `gleef push`:** Keys are sent to Gleef

**After `gleef pull`:** Local files are updated with new translations

## Configuration File Example

After running `gleef init`, you'll have a `.gleef/config.json` file like this:

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

The configuration includes:

* **localeFilePatterns**: Your pattern with `{locale}` placeholder
* **formatOptions**: Auto-detected based on your file types
* **customLocaleNames**: Only added if your files don't match standard locale names

## Common Workflows

<Info>All commands can be added to your CI/CD or build scripts to automate updating or creating translations.</Info>

### Adding New Translation Keys

1. Add new keys to your base language file (e.g., `en-US.json`)
2. Run `gleef push` to send them to Gleef
3. Review translations in Gleef Studio
4. Run `gleef pull` to sync approved translations

### Updating Existing Translations

1. Modify existing keys in your local files
2. Run `gleef push` to upload the updates
3. Review changes in Gleef Studio
4. Run `gleef pull --add-new` to sync all updates

### Working with Multiple Developers

1. Each developer runs `gleef pull` before starting work
2. Make translation changes locally
3. Run `gleef push` to upload changes
4. Coordinate reviews in Gleef Studio
5. Run `gleef pull` to get the latest approved translations

## Next Steps

<CardGroup cols={2}>
  <Card title="Learn All Commands" icon="terminal" href="/cli/commands/overview">
    Explore all available CLI commands and their options
  </Card>

  <Card title="Workflow Guide" icon="workflow" href="/cli/workflow/project-setup">
    Understand advanced workflows and best practices
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Configuration Options" icon="cog" href="/cli/configuration/config-file">
    Customize Gleef CLI for your project needs
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/cli/support/troubleshooting">
    Solve common issues and get help
  </Card>
</CardGroup>