gleef push - Developer Guide

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.

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

Usage

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:

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

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.

Basic Usage

Push All Changes

gleef push

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

Filter by Key Pattern

gleef push --match "^button\."

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

Filter by Namespace

gleef push --namespace "auth"

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

Skip Review Process

gleef push --skip-review

Publishes translations immediately without creating drafts for review.

Example Output

Pushing Changes

$ gleef push
Pushing 5 edited translations
⠋ Pushing translations to Gleef...
✔ Your translations were pushed successfully.

No Changes to Push

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

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.

Common Patterns

# 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

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

$ 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

Update locally - Change your local value to match the remote
Update remotely - Change the value in Gleef Studio
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:

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

Skip Review Mode

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

gleef push --skip-review

This is useful for:

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

Examples

Development Workflow

# 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

# Push only specific feature translations
gleef push --match "^checkout\."

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

Namespace-Specific Push

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

gleef push --namespace "auth"

Error Handling

Common Errors

Authentication Error:

Couldn't push translations: Authentication failed

Solution: Run gleef login to re-authenticate Configuration Error:

Couldn't push translations: No locale files found

Solution: Run gleef init or check your .gleef/config.json Network Error:

Couldn't push translations: Network request failed

Solution: Check internet connection and try again File Format Error:

Couldn't push translations: Invalid JSON in locale file

Solution: Fix JSON syntax errors in your locale files

Best Practices

Always pull latest changes before pushing to avoid conflicts.

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

Integration Examples

NPM Scripts

{
  "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

- name: Push translations
  run: |
    gleef login --key ${{ secrets.GLEEF_API_KEY }}
    gleef push --skip-review

Next Steps

After pushing changes:

Review in Studio

Review and approve translations in Gleef Studio

Pull Updates

Sync approved translations back to your project

​Usage

​Options

​What it does

​Basic Usage

​Push All Changes

​Filter by Key Pattern

​Filter by Namespace

​Skip Review Process

​Example Output

​Pushing Changes

​No Changes to Push

​Pattern Matching

​Common Patterns

​Complex Patterns

​Conflict Resolution

​Resolving Conflicts

​When to Use Push vs Translate

​Review Workflow

​Default Behavior (Draft Mode)

​Skip Review Mode

​Examples

​Development Workflow

​Feature Development

​Namespace-Specific Push

​Error Handling

​Common Errors

​Best Practices

​Integration Examples

​NPM Scripts

​GitHub Actions

​Next Steps

Review in Studio

Pull Updates

Usage

Options

What it does

Basic Usage

Push All Changes

Filter by Key Pattern

Filter by Namespace

Skip Review Process

Example Output

Pushing Changes

No Changes to Push

Pattern Matching

Common Patterns

Complex Patterns

Conflict Resolution

Resolving Conflicts

When to Use Push vs Translate

Review Workflow

Default Behavior (Draft Mode)

Skip Review Mode

Examples

Development Workflow

Feature Development

Namespace-Specific Push

Error Handling

Common Errors

Best Practices

Integration Examples

NPM Scripts

GitHub Actions

Next Steps