Troubleshooting

​

Installation Issues

​

Node.js Version Compatibility

npm ERR! engine Unsupported engine
npm ERR! Required: node >=18.0.0
npm ERR! Actual: v16.14.0

1. Check current version: node --version
2. Update Node.js: Download latest from nodejs.org
3. Or use nvm:
   Copy

   # Install nvm (if not installed)
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   
   # Install and use Node.js 18+
   nvm install 18
   nvm use 18
   

​

Permission Errors

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/@gleef

# Option 1: Use sudo (not recommended)
sudo npm install -g @gleef/cli

# Option 2: Configure npm to use user directory (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
npm install -g @gleef/cli

1. Run Command Prompt as Administrator
2. Install the CLI: npm install -g @gleef/cli

​

Network/Firewall Issues

npm ERR! network request to https://registry.npmjs.org/@gleef%2fcli failed

1. Check internet connection
2. Configure corporate proxy:
   Copy

   npm config set proxy http://proxy.company.com:8080
   npm config set https-proxy http://proxy.company.com:8080
   

3. Use different registry:
   Copy

   npm install -g @gleef/cli --registry https://registry.yarnpkg.com
   

​

Authentication Issues

​

Invalid API Key

The given API key doesn't seem to be valid. Please check your key and try again.

1. Verify key format: API keys start with gl_ followed by alphanumeric characters
2. Check for extra characters: Remove any spaces or newlines from the key
3. Generate new key: Visit https://app.gleef.eu/settings/api-keys
4. Re-authenticate:
   Copy

   gleef login --key YOUR_NEW_API_KEY
   

​

Authentication Storage Issues

Error: Could not save API key to configuration file

# Check permissions on config directory
ls -la ~/.config/gleef/

# Fix permissions if needed
mkdir -p ~/.config/gleef
chmod 755 ~/.config/gleef

# Check if directory exists
dir %APPDATA%\gleef

# Create if missing
mkdir %APPDATA%\gleef

​

Network Authentication Issues

Error: Network request failed - getaddrinfo ENOTFOUND api.gleef.eu

1. Check DNS: nslookup api.gleef.eu
2. Try different DNS:
   Copy

   # Use Google DNS
   export DNS_SERVER=8.8.8.8
   

3. Corporate firewall: Contact IT to whitelist *.gleef.eu
4. VPN issues: Try without VPN or with different VPN server

​

Configuration Issues

​

No Files Detected During Init

⚠ No locale files found in your project

1. Check file extensions:
   Copy

   # Verify you have supported files
   find . -name "*.json" -o -name "*.xml" -o -name "*.yaml" -o -name "*.strings"
   

2. Check .gitignore exclusions:
   Copy

   # See what files are being ignored
   git check-ignore -v src/locales/*.json
   

3. Manual configuration:
   Copy

   {
     "localeFilePatterns": [
       "path/to/your/locale/files/*.json"
     ]
   }
   

​

Invalid Configuration File

Error: Invalid configuration file at .gleef/config.json

1. Validate JSON syntax:
   Copy

   cat .gleef/config.json | jq empty
   

2. Common JSON errors:
   • Missing quotes around keys
   • Trailing commas
   • Unclosed brackets/braces
3. Reset configuration:
   Copy

   rm -rf .gleef/
   gleef init
   

​

Pattern Matching Issues

Warning: Pattern 'src/**.json' matched no files

1. Fix pattern syntax:
   Copy

   {
     "localeFilePatterns": [
       "src/**/*.json"
     ]
   }
   

2. Test patterns:
   Copy

   # Test with shell
   ls src/**/*.json
   
   # Test with find
   find . -path "src/**/*.json"
   

​

Command Execution Issues

​

”Nothing to translate” When Expecting Changes

1. Check if files have actual changes:
   Copy

   git diff src/locales/
   

2. Verify configuration patterns or run:
   Copy

   gleef init
   

3. Check for conflicts:
   Copy

   gleef pull --check
   

4. Reset and retry:
   Copy

   gleef pull
   gleef translate
   

​

Pull Command Not Updating Files

1. Check file permissions:
   Copy

   ls -la src/locales/
   chmod 644 src/locales/*.json
   

2. Verify files match patterns:
   Copy

   gleef init --list-files
   

3. Check if translations are approved in Gleef Studio
4. Force full sync:
   Copy

   gleef pull --all
   

5. Remove .gleef/lock.json

​

Conflict Resolution Issues

Conflict with remotely edited translations. Update keys with the remote value, or change them from the webapp.

1. Accept remote changes:
   Copy

   gleef pull  # Get remote version
   gleef translate  # Push remaining changes
   

2. Keep local changes:
   • Update the conflicting key in Gleef Studio to match your local version
   • Run gleef translate again
3. Manual resolution:
   • Decide on the correct value
   • Update both locally and in Gleef Studio
   • Run gleef translate

​

File Format Issues

​

JSON Syntax Errors

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

1. Find the problematic file:
   Copy

   # Check each JSON file
   for file in src/locales/*.json; do
     echo "Checking $file"
     cat "$file" | jq empty || echo "Error in $file"
   done
   

2. Common JSON issues:
   • Trailing commas: {"key": "value",} → {"key": "value"}
   • Unescaped quotes: "He said "hello"" → "He said \"hello\""
   • Missing commas: {"a": "b" "c": "d"} → {"a": "b", "c": "d"}
3. Fix with automated tools:
   Copy

   # Use jq to format properly
   jq . src/locales/en.json > temp.json && mv temp.json src/locales/en.json
   

​

XML Format Issues

Error parsing XML file: src/locales/strings.xml

1. Validate XML:
   Copy

   xmllint --noout src/locales/strings.xml
   

2. Common XML issues:
   • Unclosed tags: <string name="key">value → <string name="key">value</string>
   • Invalid characters: & → &, < → <, > → >
   • Missing declarations: Add <?xml version="1.0" encoding="UTF-8"?>

​

YAML Format Issues

Error parsing YAML file: Invalid YAML syntax

1. Validate YAML:
   Copy

   yq empty src/locales/en.yml
   

2. Common YAML issues:
   • Indentation: Use consistent spaces (not tabs)
   • Missing quotes: key: value with: colon → key: "value with: colon"
   • List formatting: Ensure proper - spacing

​

Performance Issues

​

Slow Translation Processing

1. Use pattern matching:
   Copy

   # Process specific keys only
   gleef translate --match "component.*"
   

2. Check file sizes:
   Copy

   # Find large files that might slow processing
   find src/locales -name "*.json" -exec wc -l {} + | sort -n
   

3. Optimize patterns:
   Copy

   {
     "localeFilePatterns": [
       "src/locales/*.json",
       "!**/*test*.json",
       "!**/node_modules/**"
     ]
   }
   

​

High Memory Usage

1. Process files in batches:
   Copy

   gleef translate --match "auth.*"
   gleef translate --match "nav.*"
   

2. Reduce file sizes: Split large translation files into smaller ones
3. Close other applications: Free up system memory

​

Recovery Procedures

​

Complete Reset

# 1. Backup your files
cp -r src/locales src/locales.backup

# 2. Remove configuration
rm -rf .gleef/

# 3. Clear authentication
rm -rf ~/.config/gleef  # macOS/Linux
# or
rmdir /s %APPDATA%\gleef  # Windows

# 4. Reinstall CLI
npm uninstall -g @gleef/cli
npm install -g @gleef/cli

# 5. Re-authenticate and initialize
gleef login
gleef init

# 6. Pull all translations
gleef pull --all

# 7. Restore files if needed
cp -r src/locales.backup/* src/locales/

​

Configuration Recovery

# 1. Backup current config
cp .gleef/config.json .gleef/config.json.backup

# 2. Regenerate configuration
rm .gleef/config.json
gleef init

# 3. Manually merge any custom settings from backup

​

File Recovery

# 1. Check git history
git log --oneline src/locales/

# 2. Restore from git
git checkout HEAD~1 -- src/locales/

# 3. Or pull fresh from Gleef
gleef pull --all

​

Getting Help

​

Diagnostic Information

# System information
gleef --version
node --version
npm --version

# Configuration
cat .gleef/config.json

# File patterns test
gleef init

# Network test
curl -I https://api.gleef.eu/

​

Log Files

gleef translate 2>&1 | tee gleef.log

​

Support Channels

• Documentation: docs.gleef.eu
• Email: support@gleef.eu
• Chat: 15 minutes

​

Next Steps