The .gleef/config.json file controls how Gleef CLI processes your localization files. This file is created automatically by gleef init but can be customized for complex project setups.

​
Configuration Location

The configuration file is always located at: 
your-project/
└── .gleef/
    └── config.json
This file should be committed to version control so your team shares the same configuration.

​
Basic Configuration Structure

{
  "localeFilePatterns": [
    "src/locales/{locale}.json",
    "public/i18n/{locale}/{feature}.json"
  ],
  "formatOptions": {
    "json": {
      "nested": true
    },
    "xml": {
      "nested": false
    }
  },
  "customLocaleNames": {
    "en-US": "english",
    "fr-FR": "french"
  }
}

​
Configuration Properties

​
localeFilePatterns

Type: string[]
Required: Yes Defines placeholder patterns that match your localization files. Each pattern must include the {locale} placeholder. 
{
  "localeFilePatterns": [
    "src/locales/{locale}.json",              // Simple locale files
    "public/i18n/{locale}/{feature}.json",    // Namespaced by feature
    "assets/strings/{locale}.strings",        // iOS strings files
    "config/locales/{feature}.{locale}.yml"   // Feature-first naming
  ]
}
Placeholder Syntax:
PlaceholderDescriptionExample
{locale}Required - Locale identifieren, fr-FR, es-ES
{feature}Optional - Feature/namespace namecommon, auth, dashboard
{namespace}Optional - Alternative to featureheader, footer, modal
Pattern Examples:
PatternMatchesStructure
src/{locale}.jsonsrc/en.json, src/fr.jsonSimple structure
locales/{locale}/{feature}.jsonlocales/en/common.json, locales/fr/auth.jsonLocale-first namespacing
i18n/{feature}.{locale}.jsoni18n/common.en.json, i18n/auth.fr.jsonFeature-first namespacing
assets/{locale}/strings.xmlassets/en/strings.xml, assets/fr/strings.xmlFolder-based locales

​
formatOptions

Type: object
Required: No Controls how different file formats are processed and generated. 
{
  "formatOptions": {
    "json": {
      "nested": true
    },
    "xml": {
      "nested": false
    },
    "yaml": {
      "nested": true
    }
  }
}
Format-Specific Options:

​
JSON Options

  • nested (boolean): Use nested object structure vs flat keys

​
XML Options

  • nested (boolean): Use nested elements vs flat structure

​
YAML Options

  • nested (boolean): Use nested structure vs flat keys

​
Strings Options

None

​
customLocaleNames

Type: object
Required: No Maps your company’s locale codes to the actual file or folder names in your project when they don’t match. 
{
  "customLocaleNames": {
    "en-US": "english",
    "fr-FR": "french", 
    "es-ES": "spanish",
    "zh-CN": "chinese-simplified"
  }
}
Use Cases:
  • Legacy naming conventions that can’t be changed
  • Simplified locale names (fr instead of fr-FR)
  • Descriptive filenames in existing projects
  • Platform-specific naming requirements (iOS: en.lproj)
How it works:
  • Company locale "fr-FR" maps to file/folder name "french"
  • Pattern src/{locale}.json resolves to src/french.json
  • Gleef treats this file as containing fr-FR translations

​
Advanced Configuration Examples

​
Multi-Module Project

{
  "localeFilePatterns": [
    "apps/web/src/locales/{locale}.json",
    "apps/mobile/assets/i18n/{locale}.json", 
    "packages/shared/locales/{locale}/{feature}.json"
  ],
  "formatOptions": {
    "json": {
      "nested": true
    }
  }
}

​
Cross-Platform Project

{
  "localeFilePatterns": [
    "src/web/{locale}.json",
    "ios/MyApp/{locale}.lproj/Localizable.strings",
    "android/app/src/main/res/values-{locale}/strings.xml"
  ],
  "formatOptions": {
    "json": {
      "nested": true
    },
    "xml": {
      "nested": false
    }
  },
  "customLocaleNames": {
    "en-US": "en",
    "fr-FR": "fr",
    "es-ES": "es"
  }
}

​
Namespace-Organized Project

{
  "localeFilePatterns": [
    "i18n/{feature}.{locale}.yml",
    "locales/{locale}/{feature}.json"
  ],
  "formatOptions": {
    "json": {
      "nested": true
    },
    "yaml": {
      "nested": true
    }
  }
}

​
File Structure Examples

​
Nested JSON (Default)

Configuration: 
{
  "formatOptions": {
    "json": {
      "nested": true
    }
  }
}
Output: 
{
  "auth": {
    "login": {
      "title": "Sign In",
      "email": "Email Address",
      "password": "Password"
    }
  },
  "navigation": {
    "home": "Home",
    "about": "About"
  }
}

​
Flat JSON

Configuration: 
{
  "formatOptions": {
    "json": {
      "nested": false
    }
  }
}
Output: 
{
  "auth.login.title": "Sign In",
  "auth.login.email": "Email Address", 
  "auth.login.password": "Password",
  "navigation.home": "Home",
  "navigation.about": "About"
}

​
XML Structure

Configuration: 
{
  "formatOptions": {
    "xml": {
      "nested": false
    }
  }
}
Output: 
<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <string name="auth_login_title">Sign In</string>
  <string name="auth_login_email">Email Address</string>
  <string name="navigation_home">Home</string>
</resources>

​
Configuration Validation

​
Common Validation Errors

Missing Locale Placeholder: 
Error: No {locale} placeholder found in pattern: src/translations/*.json
No Files Matched: 
Warning: Pattern 'locales/{locale}.json' matched no files. Check your file structure.
Invalid Pattern Syntax: 
Error: File path structure doesn't match pattern: src/en/common.json vs src/{locale}.json
Locale Mapping Issues: 
Warning: Some translations for locale 'fr' have been generated but not written locally.
Check your customLocaleNames configuration.

​
Troubleshooting

​
Configuration Issues

No files detected:
  • Check pattern syntax
  • Verify file paths are correct
  • Test patterns with file system tools
Wrong files included:
  • Add exclusion patterns
  • Make patterns more specific
  • Check for conflicting patterns
Format errors:
  • Validate JSON syntax
  • Check property names and values
  • Review format-specific options

​
Recovery

Reset configuration: 
rm -rf .gleef/
gleef init

​
Next Steps

File Patterns

Learn advanced file pattern matching techniques

Format Options

Master format-specific configuration options