folderweb/docs/reference/configuration.md

# Configuration Reference

Complete reference for FolderWeb configuration options.

## Configuration File

**Location**: `/custom/config.ini` (or `/app/config.ini` for defaults)

**Format**: INI format with sections

**Override Behavior**: Custom config values override defaults

## Configuration Sections

### [languages]

Controls language support and defaults.

```ini
[languages]
default = "en"
available = "en,no,fr"
```

#### default

**Type**: String  
**Required**: Yes  
**Default**: `"en"`

The primary language of your site. This language:
- Has no URL prefix
- Is used as fallback for missing translations
- Should match a translation file in `/custom/languages/` or `/app/default/languages/`

**Examples**:
```ini
default = "en"    ; English
default = "no"    ; Norwegian
default = "fr"    ; French
default = "de"    ; German
```

#### available

**Type**: Comma-separated string  
**Required**: Yes  
**Default**: `"en,no"`

List of all languages supported by your site. Must include the default language.

**Examples**:
```ini
; English only
available = "en"

; English and Norwegian
available = "en,no"

; Multiple languages
available = "en,no,fr,de,es"
```

**URL Structure**:
- Default language: `yoursite.com/page/`
- Other languages: `yoursite.com/fr/page/`, `yoursite.com/de/page/`

## File Structure

### Default Configuration

**Location**: `/app/config.ini`

```ini
[languages]
default = "no"
available = "no,en"
```

**Note**: Never modify `/app/config.ini` directly.

### Custom Configuration

**Location**: `/custom/config.ini`

Create this file to override defaults:

```ini
[languages]
default = "en"
available = "en,fr,de"
```

Only include settings you want to override.

## Configuration Loading

Configuration is loaded in this order:

1. Load `/app/config.ini` (defaults)
2. Load `/custom/config.ini` if exists
3. Merge, with custom values overriding defaults

Example:

**app/config.ini**:
```ini
[languages]
default = "no"
available = "no,en"
```

**custom/config.ini**:
```ini
[languages]
default = "en"
```

**Result**:
```ini
[languages]
default = "en"        ; From custom
available = "no,en"   ; From default (not overridden)
```

## Complete Configuration Examples

### Single Language Site

```ini
[languages]
default = "en"
available = "en"
```

URLs: All at root level (`/page/`, `/blog/`, etc.)

### Bilingual Site (English/Norwegian)

```ini
[languages]
default = "en"
available = "en,no"
```

URLs:
- English: `/page/`, `/blog/`
- Norwegian: `/no/page/`, `/no/blog/`

### Multilingual Site

```ini
[languages]
default = "en"
available = "en,no,fr,de,es"
```

URLs:
- English (default): `/page/`
- Norwegian: `/no/page/`
- French: `/fr/page/`
- German: `/de/page/`
- Spanish: `/es/page/`

## Language Codes

Use ISO 639-1 two-letter codes:

| Code | Language |
|------|----------|
| `en` | English |
| `no` | Norwegian |
| `fr` | French |
| `de` | German |
| `es` | Spanish |
| `it` | Italian |
| `pt` | Portuguese |
| `nl` | Dutch |
| `sv` | Swedish |
| `da` | Danish |
| `fi` | Finnish |
| `pl` | Polish |
| `ru` | Russian |
| `ja` | Japanese |
| `zh` | Chinese |
| `ko` | Korean |
| `ar` | Arabic |

Full list: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

## Related Configuration

### Translation Files

For each language in `available`, create a translation file:

**Pattern**: `/custom/languages/{lang}.ini`

**Example** (with `available = "en,no,fr"`):
```
custom/languages/
├── en.ini
├── no.ini
└── fr.ini
```

See [Translation Reference](translations.md) for details.

### Content Files

Language-specific content uses the same codes:

**Pattern**: `filename.{lang}.ext`

**Examples**:
- `index.md` - Default language
- `index.no.md` - Norwegian
- `index.fr.md` - French

See [Multi-Language Guide](../how-to/multi-language.md) for details.

## Validation

### Check Configuration

Verify configuration is loaded correctly:

**test-config.php**:
```php
<?php
require 'app/config.php';

$ctx = createContext();

echo "Default language: " . $ctx->defaultLang . "\n";
echo "Available languages: " . implode(', ', $ctx->availableLangs) . "\n";
echo "Current language: " . $ctx->currentLang . "\n";
echo "Language prefix: " . $ctx->langPrefix . "\n";
```

Run:
```bash
php test-config.php
```

### Common Errors

**Missing default in available**:
```ini
; Wrong - default must be in available
[languages]
default = "en"
available = "no,fr"

; Correct
[languages]
default = "en"
available = "en,no,fr"
```

**Invalid language codes**:
```ini
; Avoid - use ISO codes
available = "english,norwegian"

; Correct - ISO 639-1 codes
available = "en,no"
```

**Typos in section names**:
```ini
; Wrong
[language]
default = "en"

; Correct
[languages]
default = "en"
```

## Future Configuration Options

FolderWeb is minimal by design. Currently, only language settings are configurable.

Possible future additions:
- Date format preferences
- Timezone settings
- Content directory override
- Cache settings

For now, these are handled through code or conventions.

## Environment-Specific Configuration

To use different configs per environment:

**Option 1: Conditional Loading**

**custom/config.ini**:
```ini
[languages]
default = "en"
available = "en,no"
```

**custom/config.dev.ini**:
```ini
[languages]
default = "en"
available = "en"
```

Modify `app/config.php` to load based on environment.

**Option 2: Separate Deployments**

Use different `custom/config.ini` files per deployment:
- Development: `/custom/config.ini` with dev settings
- Production: Different `/custom/config.ini` with prod settings

## Configuration in Templates

Access configuration through context object:

```php
<!-- Current language -->
<html lang="<?= $ctx->currentLang ?>">

<!-- Available languages -->
<nav class="language-switcher">
    <?php foreach ($ctx->availableLangs as $lang): ?>
        <a href="/<?= $lang ?>/"><?= strtoupper($lang) ?></a>
    <?php endforeach; ?>
</nav>

<!-- Default language check -->
<?php if ($ctx->currentLang === $ctx->defaultLang): ?>
    <p>Viewing in default language</p>
<?php endif; ?>

<!-- Language prefix for URLs -->
<a href="<?= $ctx->langPrefix ?>/about/">About</a>
```

## Best Practices

### Keep It Simple

Only configure what's necessary. FolderWeb embraces sensible defaults.

### Match Translation Files

Ensure translation files exist for all languages:

```ini
[languages]
available = "en,no,fr"
```

Requires:
- `custom/languages/en.ini`
- `custom/languages/no.ini`
- `custom/languages/fr.ini`

### Choose Appropriate Default

Your default language should be:
- Your primary audience's language
- The language with most content
- The language you'll maintain long-term

### Document Your Choices

Add comments to explain configuration:

```ini
; Site uses English as primary language (most content)
; Norwegian and French are secondary translations
[languages]
default = "en"
available = "en,no,fr"
```

## Testing Configuration Changes

After changing configuration:

1. **Clear browser cache** (Ctrl+Shift+R or Cmd+Shift+R)
2. **Test default language**: Visit `/`
3. **Test other languages**: Visit `/no/`, `/fr/`, etc.
4. **Check navigation**: Ensure menu links include language prefix
5. **Verify translations**: Check UI strings change per language
6. **Test language switcher**: Confirm switching works

## Related

- [Multi-Language Guide](../how-to/multi-language.md)
- [Translation Reference](translations.md)
- [Metadata Reference](metadata.md)
- [Context Object Reference](templates.md#context-object)