Skip to main content

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.

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

​
Usage

gleef pull

​
Options

FlagShortDescription
--add-new-aCreates new localization keys if they are not in the current locale files
--check-cChecks for new translations without updating them (returns error if translations are missing)
--match-mFilter incoming translations by key pattern
--namespace-nFilter translations by namespace/file pattern (e.g., “auth” or “auth|common”)

​
What it does

The pull command:
  1. Fetches remote state - Gets the latest translations from Gleef
  2. Compares changes - Identifies modified and new translations
  3. Shows preview - Displays what will be updated (unless using --check)
  4. 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:
  1. Shows preview - Always shows what will change before applying
  2. Requires confirmation - Asks before overwriting local changes
  3. Preserves formatting - Maintains your file structure and indentation
  4. 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:
  1. Check recent activity - Review what happened in Gleef Studio
  2. Use patterns - Pull specific sections with --match
  3. Coordinate with team - Ensure you’re not missing context

​
Missing Translations

If expected translations aren’t appearing:
  1. Use —add-new flag - New keys require the --add-new flag
  2. Check patterns - Ensure your --match pattern is correct
  3. Verify approval - Translations must be approved in Gleef Studio

​
File Conflicts

If you have local changes that conflict:
  1. Commit local changes - Save your work before pulling
  2. Review differences - Understand what changed remotely
  3. 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