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

> Push local translations to Gleef

The `gleef push` command uploads your local translation changes (new keys and edits) to Gleef. It is the standard command for syncing your local files to Gleef.

<Note>If you want Gleef to generate AI translations and merge them back into your local files in one step, use `gleef translate` instead.</Note>

## Usage

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

## Options

| Flag            | Short | Description                                                                    |
| --------------- | ----- | ------------------------------------------------------------------------------ |
| `--match`       | `-m`  | Filter translations by key pattern                                             |
| `--namespace`   | `-n`  | Filter translations by namespace/file pattern (e.g., "auth" or "auth\|common") |
| `--skip-review` | `-s`  | Publish translations immediately instead of creating drafts                    |

## What it does

The `push` command:

1. **Analyzes local files** - Compares your local translations with remote state
2. **Detects changes** - Identifies new keys and modified translations
3. **Handles conflicts** - Checks for conflicts with remote edits
4. **Uploads changes** - Pushes your translations to Gleef
5. **Creates drafts** - Sets up translations for team review (unless `--skip-review` is used)

<Note>`gleef push` uploads what you have locally. Translations for missing locales are produced by Gleef after the push and become available via `gleef pull`. To generate AI translations and immediately write them back to your local files in one step, use `gleef translate`.</Note>

## Basic Usage

### Push All Changes

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

This will upload all new and modified translation keys in your project.

### Filter by Key Pattern

```bash theme={null}
gleef push --match "^button\."
```

Only pushes keys matching the pattern. The pattern is a JavaScript regex (see [Pattern Matching](#pattern-matching) below).

### Filter by Namespace

```bash theme={null}
gleef push --namespace "auth"
```

Only pushes translations from files matching the namespace pattern. Useful for projects with multiple namespace/feature files.

### Skip Review Process

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

Publishes translations immediately without creating drafts for review.

## Example Output

### Pushing Changes

```bash theme={null}
$ gleef push
Pushing 5 edited translations
⠋ Pushing translations to Gleef...
✔ Your translations were pushed successfully.
```

### No Changes to Push

```bash theme={null}
$ gleef push
Nothing new to push
```

## Pattern Matching

The `--match` flag accepts a JavaScript regular expression that is tested against each translation key. It is **unanchored**, so a pattern matches if it appears anywhere in the key. If the pattern isn't valid regex, it falls back to a plain substring check.

<Note>This is regex, not a glob. `.` matches any character and `*` means "zero or more of the previous character", so a pattern like `*.title` is invalid regex and won't behave like a glob.</Note>

### Common Patterns

```bash theme={null}
# Match keys starting with "button."
gleef push --match "^button\."

# Match keys ending with ".title"
gleef push --match "\.title$"

# Match keys containing "auth."
gleef push --match "auth\."
```

### Complex Patterns

```bash theme={null}
# Match keys containing "button." OR "nav." (regex alternation)
gleef push --match "button\.|nav\."

# Match nested keys like components.<anything>.label
gleef push --match "^components\..+\.label$"
```

## Conflict Resolution

If there are conflicts with remotely edited translations, the command will stop and show details:

```bash theme={null}
$ gleef push
en-US
  welcome.title
    Local value: Welcome to our app
    Remote value: Welcome to our application

Conflict with remotely edited translations. Update keys with the remote value, or change them from the webapp.
```

### Resolving Conflicts

1. **Update locally** - Change your local value to match the remote
2. **Update remotely** - Change the value in Gleef Studio
3. **Pull first** - Run `gleef pull` to get latest changes, then push

## When to Use Push vs Translate

| Use `gleef push` when...                       | Use `gleef translate` when...                                            |
| ---------------------------------------------- | ------------------------------------------------------------------------ |
| You're adding new keys (the standard workflow) | You want AI translations written back into your local files immediately  |
| You're updating existing translations          | You need the AI output available locally before running `gleef pull`     |
| You have translations from another source      | You want a single command that generates and merges translations locally |

## Review Workflow

### Default Behavior (Draft Mode)

By default, changes are pushed as drafts for team review:

1. **Changes uploaded** - Your edits are pushed to Gleef
2. **Drafts created** - Changes are marked as drafts in Gleef Studio
3. **Team reviews** - Your team can review and approve in Gleef Studio
4. **Pull approved** - Use `gleef pull` to sync approved translations

### Skip Review Mode

With `--skip-review`, changes are published immediately:

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

This is useful for:

* Automated workflows
* Non-critical updates
* When you don't need team review

## Examples

### Development Workflow

```bash theme={null}
# Add or edit translations in your local files
# Then push them to Gleef
gleef push

# Ask for review in Gleef Studio
# Pull approved translations
gleef pull
```

### Feature Development

```bash theme={null}
# Push only specific feature translations
gleef push --match "^checkout\."

# Test the changes
gleef pull --match "^checkout\."
```

### Namespace-Specific Push

```bash theme={null}
# Push only authentication-related files
gleef push --namespace "auth"

# Push multiple namespaces
gleef push --namespace "auth|common"

# Combine namespace and pattern filtering
gleef push --namespace "components" --match "^button\."
```

**Example Use Case:**

If your project structure is:

```
locales/
  en/
    auth.json
    common.json
    components.json
  fr/
    auth.json
    common.json
    components.json
```

You can push changes for just the auth namespace:

```bash theme={null}
gleef push --namespace "auth"
```

## Error Handling

### Common Errors

**Authentication Error:**

```bash theme={null}
Couldn't push translations: Authentication failed
```

*Solution:* Run `gleef login` to re-authenticate

**Configuration Error:**

```bash theme={null}
Couldn't push translations: No locale files found
```

*Solution:* Run `gleef init` or check your `.gleef/config.json`

**Network Error:**

```bash theme={null}
Couldn't push translations: Network request failed
```

*Solution:* Check internet connection and try again

**File Format Error:**

```bash theme={null}
Couldn't push translations: Invalid JSON in locale file
```

*Solution:* Fix JSON syntax errors in your locale files

## Best Practices

<Tip>Always pull latest changes before pushing to avoid conflicts.</Tip>

1. **Pull latest changes** - `gleef pull` to get recent updates
2. **Use patterns for targeted updates** - Filter with `--match` for focused pushes
3. **Review in Gleef Studio** - Check translations quality and ask for review
4. **Coordinate with team** - Ensure reviewers know about pending changes

## Integration Examples

### NPM Scripts

```json theme={null}
{
  "scripts": {
    "i18n:push": "gleef push",
    "i18n:push:publish": "gleef push --skip-review",
    "i18n:push:feature": "gleef push --match",
    "i18n:push:namespace": "gleef push --namespace"
  }
}
```

### GitHub Actions

```yaml theme={null}
- name: Push translations
  run: |
    gleef login --key ${{ secrets.GLEEF_API_KEY }}
    gleef push --skip-review
```

## Next Steps

After pushing changes:

<CardGroup cols={2}>
  <Card title="Review in Studio" icon="eye" href="/studio/review">
    Review and approve translations in Gleef Studio
  </Card>

  <Card title="Pull Updates" icon="download" href="/cli/commands/pull">
    Sync approved translations back to your project
  </Card>
</CardGroup>