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

> Generate AI translations with Gleef and merge them back into your local files

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.

<Note>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.</Note>

## Usage

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

1. **Analyzes local files** - Compares your local translations with remote state
2. **Detects changes** - Identifies new keys and modified translations
3. **Handles conflicts** - Checks for conflicts with remote edits
4. **Sends for translation** - Uploads keys to Gleef's AI translation service
5. **Updates local files** - Merges generated translations back to your files
6. **Creates drafts** - Sets up translations for team review (unless `--skip-review` is used)

## Basic Usage

### Push All Changes

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

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

### Filter by Key Pattern

```bash theme={null}
gleef translate --match "^button\."
```

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

### Filter by Namespace

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

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

### Skip Review Process

```bash theme={null}
gleef translate --skip-review
```

Publishes translations immediately without creating drafts for review.

## Example Output

### Processing New Translations

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

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

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

<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.</Note>

### Common Patterns

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

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

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

1. **Update locally** - Change your local value to match the remote
2. **Update remotely** - Change the value in Gleef Studio
3. **Pull first** - Run `gleef pull` to get latest changes, then translate

## Translation Process

### New Keys

When you add new translation keys:

```json theme={null}
{
  "welcome": {
    "title": "Welcome to our app",
    "subtitle": "Get started with our amazing features"
  }
}
```

The `translate` command will:

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

### Modified Keys

When you change existing translations:

```json5 theme={null}
{
  "welcome": {
    "title": "Welcome to our average app", // [!code --]
    "title": "Welcome to our amazing app", // [!code ++]
  }
}
```

The command will:

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

## Review Workflow

### Default Behavior (Draft Mode)

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

1. **Translations generated** - AI creates translations for all target languages
2. **Drafts created** - Translations are marked as drafts in Gleef Studio, where you can ask for a review
3. **Team reviews** - Your team can review and approve in Gleef Studio
4. **Pull approved** - Use `gleef pull` to sync approved translations

### Skip Review Mode

With `--skip-review`, translations are published immediately:

```bash theme={null}
gleef translate --skip-review
```

This is useful for:

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

## Examples

### Development Workflow

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

```bash theme={null}
# Work on a specific feature
gleef translate --match "^checkout\."

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

### Bulk Updates

```bash theme={null}
# Translate all incomplete navigation-related text
gleef translate --match "^(nav|menu|header)\."
```

### Namespace-Specific Translation

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

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

## Error Handling

### Common Errors

**Authentication Error:**

```bash theme={null}
Couldn't generate and push translations: Authentication failed
```

*Solution:* Run `gleef login` to re-authenticate

**Configuration Error:**

```bash theme={null}
Couldn't generate and push translations: No locale files found
```

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

**Network Error:**

```bash theme={null}
Couldn't generate and push translations: Network request failed
```

*Solution:* Check internet connection and try again

**File Format Error:**

```bash theme={null}
Couldn't generate and push translations: Invalid JSON in locale file
```

*Solution:* Fix JSON syntax errors in your locale files

## Best Practices

<Tip>Always pull latest changes before pushing new translations to avoid conflicts.</Tip>

1. **Pull latest changes** - `gleef pull` to get recent updates
2. **Use patterns for large translation jobs** - Filter with `--match` for focused updates
3. **Review in Gleef Studio** - Check AI translations quality and ask for a review there or publish
4. **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.

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

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

```yaml theme={null}
- name: Push translations
  run: |
    gleef login --key ${{ secrets.GLEEF_API_KEY }}
    gleef translate --skip-review
```

## Next Steps

After pushing translations:

<CardGroup cols={2}>
  <Card title="Review in Studio" icon="eye" href="">
    Review and approve translations in Gleef Studio
  </Card>

  <Card title="Pull Updates" icon="download" href="/cli/commands/pull">
    Sync approved translations back to your project
  </Card>
</CardGroup>