gleef pull - Developer Guide

The gleef pull command downloads the latest approved translations from Gleef and updates your local localization files.

Usage

gleef pull

Options

Flag	Short	Description
`--add-new`	`-a`	Creates new localization keys if they are not in the current locale files
`--check`	`-c`	Checks for new translations without updating them (returns error if translations are missing)
`--match`	`-m`	Filter incoming translations by key pattern
`--namespace`	`-n`	Filter translations by namespace/file pattern (e.g., “auth” or “auth\|common”)

What it does

The pull command:

Fetches remote state - Gets the latest translations from Gleef
Compares changes - Identifies modified and new translations
Shows preview - Displays what will be updated (unless using --check)
Updates files - Applies changes to your local localization files

Basic Usage

Pull Updates Only

gleef pull

This updates existing keys with new translations but doesn’t add new keys.

Add New Translations

gleef pull --add-new

This updates existing keys AND adds new translation keys that were created remotely.

Filter by Key Pattern

gleef pull --match "^feature\."

Only pulls keys matching the pattern. The pattern is a JavaScript regular expression tested against each key (unanchored), with a fallback to a plain substring check if the pattern isn’t valid regex.

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. Use \.title$ to match keys ending with .title.

Filter by Namespace

gleef pull --namespace "auth"

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

Check for Updates

gleef pull --check

This checks if updates are available without applying them. Useful for CI/CD to verify translation status.

Example Output

Updates Available

$ gleef pull
The following translations will be updated:
en-US
  welcome.title
  welcome.subtitle
fr-FR
  welcome.title
  welcome.subtitle

? Do you wish to continue? This might overwrite your local changes. (Y/n)
Translation files updated successfully.

New Keys Available (with —add-new)

$ gleef pull --add-new
The following translations will be updated:
en-US
  welcome.title
fr-FR
  welcome.title

5 translations will be added.

? Do you wish to continue? This might overwrite your local changes. (Y/n)
Translation files updated successfully.

Nothing to Update

$ gleef pull
Nothing to update. Your translations are up to date.

Check Mode

$ gleef pull --check
Translations check: 3 translations are outdated. Please run `gleef pull` to update them.

The —add-new Flag

By default, pull only updates existing keys. Use --add-new to also add new keys:

Without —add-new (default)

✅ Updates existing translation values
❌ Ignores new keys created remotely
✅ Safe for stable releases

With —add-new

✅ Updates existing translation values
✅ Adds new keys created remotely
⚠️ May require code changes to handle new keys

Filtering Options

Pattern Matching with —add-new

When using --add-new, you can filter which new keys to add:

# Only add new keys matching the pattern
gleef pull --add-new --match "^components\."

# Add new keys for specific features
gleef pull --add-new --match "^(auth|profile)\."

Namespace Filtering

Filter translations by namespace/file pattern. This is useful when you have multiple namespaced files per locale:

# Pull only auth-related translations
gleef pull --namespace "auth"

# Pull multiple namespaces using pipe syntax
gleef pull --namespace "auth|common"

# Combine with --add-new to add keys only to specific namespaces
gleef pull --add-new --namespace "auth"

# Combine with --match for fine-grained control
gleef pull --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 pull updates for just the auth namespace:

gleef pull --namespace "auth"

Multiple File Namespaces

If your project has multiple files per locale, you’ll be prompted to choose where new keys should be added:

$ gleef pull --add-new
Multiple files found for some locales. Choose which file pattern to add new translations to:
> Files matching: src/locales/*.json
  Files matching: src/components/*.json

This ensures new keys are added to the correct files based on your project structure.

Conflict Prevention

The pull command is designed to be safe:

Shows preview - Always shows what will change before applying
Requires confirmation - Asks before overwriting local changes
Preserves formatting - Maintains your file structure and indentation
Atomic updates - Either all changes apply or none do

Examples

Feature Integration

# Pull new keys added by other team members
gleef pull --add-new --match "^newfeature\."

# Integrate the keys into your code
# Then push your own translations
gleef push

Namespace-Specific Updates

# Pull updates only for authentication files
gleef pull --namespace "auth"

# Pull and add new keys for multiple namespaces
gleef pull --add-new --namespace "auth|common"

Release Preparation (No CI)

# Get latest validated updates before release
gleef pull

CI/CD Integration

# Check if translations are up to date
if ! gleef pull --check; then
  echo "Translations are outdated. Please run 'gleef pull' locally."
  exit 1
fi

# Or automatically update in CI
gleef pull --add-new --skip-confirm

Error Handling

Common Errors

No Changes Error:

Nothing to update. Your translations are up to date.

This is normal - no action needed Network Error:

Error: Network request failed

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

Error: Cannot write to locale file

Solution: Check file permissions and ensure files aren’t locked Configuration Error:

Error: No locale files found

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

Troubleshooting

Large Number of Changes

If you see many unexpected changes:

Check recent activity - Review what happened in Gleef Studio
Use patterns - Pull specific sections with --match
Coordinate with team - Ensure you’re not missing context

Missing Translations

If expected translations aren’t appearing:

Use —add-new flag - New keys require the --add-new flag
Check patterns - Ensure your --match pattern is correct
Verify approval - Translations must be approved in Gleef Studio

File Conflicts

If you have local changes that conflict:

Commit local changes - Save your work before pulling
Review differences - Understand what changed remotely
Merge carefully - Decide which version to keep

Integration Examples

NPM Scripts

{
  "scripts": {
    "i18n:pull": "gleef pull",
    "i18n:pull:all": "gleef pull --add-new",
    "i18n:check": "gleef pull --check",
    "i18n:pull:namespace": "gleef pull --namespace"
  }
}

Git Hooks

#!/bin/bash
# pre-push hook - ensure translations are up to date
if ! gleef pull --check; then
  echo "Translations are outdated. Run 'gleef pull' before pushing."
  exit 1
fi

GitHub Actions

- name: Check translations
  run: |
    gleef login --key ${{ secrets.GLEEF_API_KEY }} # Or use the env variable directly
    gleef pull --check

Next Steps

After pulling translations:

Push Changes

Send your new translation keys to Gleef

Configuration

Customize how files are processed

​Usage

​Options

​What it does

​Basic Usage

​Pull Updates Only

​Add New Translations

​Filter by Key Pattern

​Filter by Namespace

​Check for Updates

​Example Output

​Updates Available

​New Keys Available (with —add-new)

​Nothing to Update

​Check Mode

​The —add-new Flag

​Without —add-new (default)

​With —add-new

​Filtering Options

​Pattern Matching with —add-new

​Namespace Filtering

​Multiple File Namespaces

​Conflict Prevention

​Examples

​Feature Integration

​Namespace-Specific Updates

​Release Preparation (No CI)

​CI/CD Integration

​Error Handling

​Common Errors

​Troubleshooting

​Large Number of Changes

​Missing Translations

​File Conflicts

​Integration Examples

​NPM Scripts

​Git Hooks

​GitHub Actions

​Next Steps

Push Changes

Configuration

Usage

Options

What it does

Basic Usage

Pull Updates Only

Add New Translations

Filter by Key Pattern

Filter by Namespace

Check for Updates

Example Output

Updates Available

New Keys Available (with —add-new)

Nothing to Update

Check Mode

The —add-new Flag

Without —add-new (default)

With —add-new

Filtering Options

Pattern Matching with —add-new

Namespace Filtering

Multiple File Namespaces

Conflict Prevention

Examples

Feature Integration

Namespace-Specific Updates

Release Preparation (No CI)

CI/CD Integration

Error Handling

Common Errors

Troubleshooting

Large Number of Changes

Missing Translations

File Conflicts

Integration Examples

NPM Scripts

Git Hooks

GitHub Actions

Next Steps