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

> Get the latest translations from Gleef and update your local files

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

## Usage

```bash theme={null}
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:

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

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

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

### Add New Translations

```bash theme={null}
gleef pull --add-new
```

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

### Filter by Key Pattern

```bash theme={null}
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.

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

### Filter by Namespace

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

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

### Check for Updates

```bash theme={null}
gleef pull --check
```

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

## Example Output

### Updates Available

```bash theme={null}
$ 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)

```bash theme={null}
$ 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

```bash theme={null}
$ gleef pull
Nothing to update. Your translations are up to date.
```

### Check Mode

```bash theme={null}
$ 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
$ 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

```bash theme={null}
# 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

```bash theme={null}
# 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)

```bash theme={null}
# Get latest validated updates before release
gleef pull
```

### CI/CD Integration

```bash theme={null}
# 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:**

```bash theme={null}
Nothing to update. Your translations are up to date.
```

*This is normal - no action needed*

**Network Error:**

```bash theme={null}
Error: Network request failed
```

*Solution:* Check internet connection and try again

**File Permission Error:**

```bash theme={null}
Error: Cannot write to locale file
```

*Solution:* Check file permissions and ensure files aren't locked

**Configuration Error:**

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
#!/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

```yaml theme={null}
- 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:

<CardGroup cols={2}>
  <Card title="Push Changes" icon="upload" href="/cli/commands/push">
    Send your new translation keys to Gleef
  </Card>

  <Card title="Configuration" icon="cog" href="/cli/configuration/config-file">
    Customize how files are processed
  </Card>
</CardGroup>