gleef translate - Developer Guide

The gleef translate command sends your new and modified keys to Gleef, generates AI translations for the missing locales, and writes the generated translations back into your local files in a single step.

For the standard workflow of uploading new and updated translations, use gleef push. Use gleef translate only when you specifically want the generated translations merged into your local files immediately, rather than pulling them later.

Usage

gleef translate

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 translate 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
Sends for translation - Uploads keys to Gleef’s AI translation service
Updates local files - Merges generated translations back to your files
Creates drafts - Sets up translations for team review (unless --skip-review is used)

Basic Usage

Push All Changes

gleef translate

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

Filter by Key Pattern

gleef translate --match "^button\."

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

Filter by Namespace

gleef translate --namespace "auth"

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

Skip Review Process

gleef translate --skip-review

Publishes translations immediately without creating drafts for review.

Example Output

Processing New Translations

$ gleef translate
Processing 12 new translations
⠋ Translating with Gleef AI
✔ Your files were translated successfully. Your team can review them from Gleef Studio.

Processing Mixed Changes

$ gleef translate
Processing 8 new translations
Pushing 3 edited translations
⠋ Translating with Gleef AI
✔ Your files were translated successfully. Your team can review them from Gleef Studio.

No Changes to Process

$ gleef translate
Nothing new to translate

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 translate --match "^button\."

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

# Match keys containing "auth."
gleef translate --match "auth\."

Complex Patterns

# Match keys containing "button." OR "nav." (regex alternation)
gleef translate --match "button\.|nav\."

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

Conflict Resolution

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

$ gleef translate
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 translate

Translation Process

New Keys

When you add new translation keys:

{
  "welcome": {
    "title": "Welcome to our app",
    "subtitle": "Get started with our amazing features"
  }
}

The translate command will:

Detect the new keys
Send them to Gleef AI for translation
Generate translations in all your target languages
Update your local files with the generated translations

Modified Keys

When you change existing translations:

{
  "welcome": {
    "title": "Welcome to our average app", 
    "title": "Welcome to our amazing app", 
  }
}

The command will:

Detect the modification
Push the edited translation as draft or directly publish it
Preserve translations in other languages

Review Workflow

Default Behavior (Draft Mode)

By default, translations are created as drafts for team review:

Translations generated - AI creates translations for all target languages
Drafts created - Translations are marked as drafts in Gleef Studio, where you can ask for a review
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, translations are published immediately:

gleef translate --skip-review

This is useful for:

Automated workflows
Non-critical translations
When you trust the AI output completely

Examples

Development Workflow

# Add new keys to your base language file
# Then push for translation
gleef translate

# Ask for review of the draft in the Gleef Studio
# Pull approved translations
gleef pull

Feature Development

# Work on a specific feature
gleef translate --match "^checkout\."

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

Bulk Updates

# Translate all incomplete navigation-related text
gleef translate --match "^(nav|menu|header)\."

Namespace-Specific Translation

# Translate only authentication-related files
gleef translate --namespace "auth"

# Translate multiple namespaces
gleef translate --namespace "auth|common"

# Combine namespace and pattern filtering
gleef translate --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 translations for just the auth namespace:

gleef translate --namespace "auth"

Error Handling

Common Errors

Authentication Error:

Couldn't generate and push translations: Authentication failed

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

Couldn't generate and push translations: No locale files found

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

Couldn't generate and push translations: Network request failed

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

Couldn't generate and push translations: Invalid JSON in locale file

Solution: Fix JSON syntax errors in your locale files

Best Practices

Always pull latest changes before pushing new translations to avoid conflicts.

Pull latest changes - gleef pull to get recent updates
Use patterns for large translation jobs - Filter with --match for focused updates
Review in Gleef Studio - Check AI translations quality and ask for a review there or publish
Coordinate with team - Ensure reviewers know about pending translations

Integration Examples

Git Hooks

This hook would filter keys based on the committed file name, given that the new keys follow a precise naming convention.

#!/bin/bash
# pre-commit hook
gleef translate --match "$(git diff --name-only --cached | grep -E '\.(json|xml|yaml|strings)$' | head -1 | cut -d'/' -f1).*"

NPM Scripts

{
  "scripts": {
    "i18n:push": "gleef translate",
    "i18n:push:publish": "gleef translate --skip-review",
    "i18n:push:feature": "gleef translate --match",
    "i18n:push:namespace": "gleef translate --namespace"
  }
}

GitHub Actions

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

Next Steps

After pushing translations:

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

​Processing New Translations

​Processing Mixed Changes

​No Changes to Process

​Pattern Matching

​Common Patterns

​Complex Patterns

​Conflict Resolution

​Resolving Conflicts

​Translation Process

​New Keys

​Modified Keys

​Review Workflow

​Default Behavior (Draft Mode)

​Skip Review Mode

​Examples

​Development Workflow

​Feature Development

​Bulk Updates

​Namespace-Specific Translation

​Error Handling

​Common Errors

​Best Practices

​Integration Examples

​Git Hooks

​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

Processing New Translations

Processing Mixed Changes

No Changes to Process

Pattern Matching

Common Patterns

Complex Patterns

Conflict Resolution

Resolving Conflicts

Translation Process

New Keys

Modified Keys

Review Workflow

Default Behavior (Draft Mode)

Skip Review Mode

Examples

Development Workflow

Feature Development

Bulk Updates

Namespace-Specific Translation

Error Handling

Common Errors

Best Practices

Integration Examples

Git Hooks

NPM Scripts

GitHub Actions

Next Steps