# Language (new)

## Overview

{% hint style="warning" %}
The new language concept will be released with version 4.3+
{% endhint %}

TeamCal Neo 4.3+ has modernized its language system from 4 large files to a more efficient controller-specific structure. This guide helps you migrate your custom language files to the new system while maintaining full compatibility.

## 🚀 Quick Start

**Good News**: Your existing language files still work! The new system automatically falls back to your current files if the new structure isn't available.

**Migration is Optional**: You can continue using your current 4-file structure indefinitely. The new system only activates when you set `USE_SPLIT_LANGUAGE_FILES` to true in config.app.php.

## What's Changed

### Old System (Still Supported)

```
languages/
├── english.php          # Framework strings (~1,026 keys)
├── english.app.php      # Application strings (~730 keys)  
├── english.gdpr.php     # GDPR strings (~13 keys)
└── english.log.php      # Logging strings (~103 keys)
```

### New System (Optional Performance Upgrade)

```
languages/
└── english/             # Language folder
    ├── core.php         # Essential strings (~26 keys)
    ├── about.php        # About page strings (~8 keys)
    ├── absence.php      # Absence management (~94 keys)
    ├── calendar.php     # Calendar features (~89 keys)
    ├── user.php         # User management (~45 keys)
    └── ...              # 35 total controller files
```

## Benefits of Migration

### Performance Improvements

* **80-99% Memory Reduction**: Load only 26-355 keys instead of 1,872 keys per page
* **Faster Loading**: 2-4 small files instead of 4 large files per request
* **Better Organization**: Find language keys by feature/controller

### Developer Experience

* **Familiar Structure**: Same PHP `$LANG` array syntax you already know
* **Logical Organization**: Strings grouped by functionality (users, calendar, etc.)
* **Easier Maintenance**: One file per feature makes updates intuitive

## Migration Process

### Step 1: Create Language Directory

Create a folder for your language in `src/languages/`:

```
src/languages/your_language/
```

### Step 2: Create Split Language Files

Start with the most important controllers for your site. Here's the key mapping:

#### Essential Files (Start Here)

* **core.php** - Global strings used everywhere
* **login.php** - Login/authentication strings
* **home.php** - Homepage strings
* **users.php** - User management strings
* **calendar.php** - Calendar features

#### Complete Language File List

| Controller File     | Purpose             | Typical Keys            | Used By Controllers                                                                                                                      |
| ------------------- | ------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| core.php            | Global strings      | alert\_, btn\_, general | All controllers (auto-loaded)                                                                                                            |
| about.php           | About page          | about\_                 | about.php                                                                                                                                |
| absence.php         | Absence management  | abs\_, absum\_          | absenceedit.php, absenceicon.php, absences.php, absum.php, remainder.php, statsabsence.php, statsabstype.php                             |
| alert.php           | System alerts       | alert\_                 | alert.php (auto-loaded)                                                                                                                  |
| attachment.php      | File attachments    | attach\_                | attachments.php                                                                                                                          |
| bulkedit.php        | Bulk editing        | bulkedit\_              | bulkedit.php                                                                                                                             |
| calendar.php        | Calendar features   | cal\_, caledit\_        | absenceedit.php, absum.php, bulkedit.php, calendaredit.php, calendarview\.php, groupcalendaredit.php, month.php, remainder.php, year.php |
| calendaroptions.php | Calendar options    | calopt\_                | calendaredit.php, calendaroptions.php, calendarview\.php                                                                                 |
| config.php          | Configuration       | config\_                | config.php                                                                                                                               |
| database.php        | Database management | db\_                    | database.php                                                                                                                             |
| daynote.php         | Daily notes         | daynote\_               | daynote.php                                                                                                                              |
| declination.php     | Declinations        | decl\_                  | declination.php                                                                                                                          |
| email.php           | Email system        | email\_                 | Various email functions                                                                                                                  |
| gdpr.php            | Data privacy        | gdpr\_                  | dataprivacy.php, gdpr.php                                                                                                                |
| group.php           | Group management    | group\_                 | groupedit.php, groups.php                                                                                                                |
| holiday.php         | Holiday management  | holiday\_               | holidayedit.php, holidays.php                                                                                                            |
| import.php          | Data import         | import\_                | userimport.php                                                                                                                           |
| imprint.php         | Legal imprint       | imprint\_               | imprint.php                                                                                                                              |
| log.php             | System logging      | log\_                   | log.php                                                                                                                                  |
| login.php           | Authentication      | login\_, password\_     | login.php, login2fa.php, logout.php, passwordreset.php, setup2fa.php, verify.php                                                         |
| maintenance.php     | System maintenance  | maint\_                 | maintenance.php                                                                                                                          |
| message.php         | User messaging      | msg\_                   | messageedit.php, messages.php                                                                                                            |
| month.php           | Monthly view        | month\_                 | month.php, monthedit.php                                                                                                                 |
| password.php        | Password management | pwd\_                   | passwordrequest.php, passwordreset.php, register.php, useradd.php, useredit.php                                                          |
| pattern.php         | Recurring patterns  | pattern\_               | patternadd.php, patternedit.php, patterns.php                                                                                            |
| permission.php      | User permissions    | perm\_                  | permissions.php                                                                                                                          |
| profile.php         | User profiles       | profile\_               | bulkedit.php, profile.php, useradd.php, useredit.php, viewprofile.php                                                                    |
| region.php          | Regional settings   | region\_                | regionedit.php, regions.php                                                                                                              |
| register.php        | User registration   | register\_              | register.php                                                                                                                             |
| remainder.php       | Remainder tracking  | remainder\_             | remainder.php, statsremainder.php                                                                                                        |
| role.php            | User roles          | role\_                  | roleedit.php, roles.php                                                                                                                  |
| statistics.php      | Reports/analytics   | stats\_                 | statistics.php, statsabsence.php, statsabstype.php, statspresence.php, statsremainder.php                                                |
| upload.php          | File uploads        | upload\_                | upload functions (auto-loaded)                                                                                                           |
| user.php            | User management     | user\_                  | useradd.php, useredit.php, userimport.php, users.php                                                                                     |
| year.php            | Yearly view         | year\_                  | year.php                                                                                                                                 |

### Step 3: Copy Keys from Legacy Files

1. Open your existing `english.app.php`
2. Find keys that start with the controller prefix (e.g., `abs_` for absence.php)
3. Copy them to the new controller file
4. Do this for all four legacy language files

Example for `absence.php`:

```php
<?php
/**
 * Absence Management Language File
 * 
 * Contains all language strings for absence-related functionality
 * including absence types, editing, and reporting.
 */

// Absence list and management
$LANG['abs_list_title'] = 'Absence Types';
$LANG['abs_name'] = 'Name';
$LANG['abs_symbol'] = 'Symbol';
$LANG['abs_color'] = 'Color';

// Absence editing
$LANG['abs_edit_title'] = 'Edit Absence Type';
$LANG['abs_allowance'] = 'Allowance';
$LANG['abs_factor'] = 'Factor';

// Add all your custom abs_ keys here...
?>
```

### Step 4: Test Your Migration

In `src/config/config.app.php`, set:

```php
define('USE_SPLIT_LANGUAGE_FILES', TRUE);
```

1. Visit different pages on your site
2. Look for missing strings or errors
3. Add missing keys to the appropriate controller files

## Support and Resources

### Getting Help

* **Check logs**: Look for PHP errors in your error logs
* **Test incrementally**: Migrate one controller at a time
* **Use fallback**: Keep old system active during migration
* **Ask for help**: Contact support if you encounter issues

**Remember**: Migration is optional and gradual. Your existing files continue to work, and you can migrate at your own pace while immediately benefiting from improved performance on migrated controllers.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lewe.gitbook.io/teamcal-neo/administration/language-new.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.