---
name: manage-theme-translations
description: Use when adding, updating, or maintaining language translation files for website themes under src/templates/{theme}/translations/.
---

# Manage Theme Translations

Use this skill when introducing or localizing strings specific to a website theme (e.g. hero copy, kicker titles, stats labels, footer notes).

## File Layout

Theme translations reside inside the theme folder and are loaded automatically by `src/settings/helpers.php`:

```
src/templates/{theme}/translations/
├── es.php
├── pt.php
├── br.php  (alias)
└── {lang}.php
```

## Loader Architecture

In `src/settings/helpers.php`:

```php
if (file_exists(THEME_PATH . 'translations/' . LANGUAGE . '.php')) {
  require_once THEME_PATH . 'translations/' . LANGUAGE . '.php';
}
```

The file runs after the global language file (`src/languages/{lang}.php`) is loaded, allowing themes to supplement or override UI strings.

## Translation File Conventions

1. **Merge Pattern**: Always merge into `$locales[LANGUAGE]` preserving existing keys:
   ```php
   <?php
   $locales[LANGUAGE] = array_merge($locales[LANGUAGE] ?? [], [
     'English source string' => 'Translated target string',
     'Welcome to the server' => 'Bienvenido al servidor',
   ]);
   ```

2. **Language Aliases**: For dialects that share translations (such as Brazilian Portuguese `br` and European Portuguese `pt`), use alias inclusion:
   ```php
   <?php
   require_once __DIR__ . '/pt.php';
   $locales['br'] = $locales['pt'];
   ```

3. **No Dynamic Logic**: Keep translation files purely declarative dictionary maps.

4. **Escaping**: Match existing project conventions. Strings may contain markup or entity references; do not introduce extra escaping unless specified.

## Validation

- Run `php -l` on all added translation files.
- Switch `LANGUAGE` or test with URL language prefixes (`/es/`, `/pt/`, `/en/`) to confirm strings resolve through `__('String')`.