---
title: "Administrator Manual"
manual: "Netresearch TextDB"
version: "main"
source: "Administrator/Index.rst"
rendered: "2026-09-30T23:05:19+00:00"
---

# Administrator Manual {#administrator}

## Overview {#admin-overview}

This section covers administrative tasks for managing the TextDB extension,
including setup, maintenance, permissions, and advanced configuration.

## Installation & Setup {#admin-installation}

### Initial Setup Checklist {#initial-setup-checklist}

1.  ☐ Install extension via Composer
1.  ☐ Update database schema
1.  ☐ Create storage folder
1.  ☐ Configure extension settings
1.  ☐ Set up user permissions
1.  ☐ Create component/type/environment records
1.  ☐ Test with sample translations

### Detailed Setup Steps {#detailed-setup-steps}

**1\. Create Storage Folder**

```none
Page Tree:
└── [Root]
    └── TextDB Translations (Folder)
        ├── [pid: 123]
        └── Language: Default + All Site Languages
```

**2\. Extension Configuration**

Navigate to **Admin Tools > Settings > Extension Configuration > nr_textdb**

```none
textDbPid = 123
createIfMissing = 1
```

**3\. Language Setup**

Ensure site languages are configured:

```yaml
# config/sites/main/config.yaml
languages:
  -
    languageId: 0
    title: English
    navigationTitle: English
    base: /
    locale: en_US.UTF-8
  -
    languageId: 1
    title: German
    navigationTitle: Deutsch
    base: /de/
    locale: de_DE.UTF-8
```

## User Permissions {#admin-permissions}

### Backend User Groups {#backend-user-groups}

Create dedicated user groups for TextDB access:

#### TextDB Editors {#textdb-editors}

```none
Module Access:
✓ Netresearch
✓ Netresearch TextDB

Table Access (Modify):
✓ tx_nrtextdb_domain_model_translation

Table Access (Read):
✓ tx_nrtextdb_domain_model_component
✓ tx_nrtextdb_domain_model_type
✓ tx_nrtextdb_domain_model_environment

Page Access:
✓ TextDB Translations Folder (pid: 123)
```

#### TextDB Administrators {#textdb-administrators}

```none
Module Access:
✓ Netresearch
✓ Netresearch TextDB

Table Access (Full):
✓ tx_nrtextdb_domain_model_translation
✓ tx_nrtextdb_domain_model_component
✓ tx_nrtextdb_domain_model_type
✓ tx_nrtextdb_domain_model_environment

Page Access:
✓ TextDB Translations Folder (full access)
```

### Setting Up Permissions {#setting-up-permissions}

1.  Navigate to **System > Backend Users > Backend User Groups**
1.  Create/Edit user group
1.  **Access Lists** tab:

    -   Select modules
    -   Select table permissions
1.  **Mounts and Workspaces** tab:

    -   Add DB Mount to TextDB folder
1.  Assign users to the group

## Data Management {#admin-data-management}

### Components {#components}

Components organize translations logically (e.g., "website", "shop", "blog").

**Create Component:**

1.  Go to **List** module
1.  Navigate to TextDB storage folder
1.  Click **Create new record**
1.  Select **Component**
1.  Enter component details

### Types {#types}

Types categorize translations by usage (e.g., "label", "message", "error").

**Create Type:**

1.  Navigate to TextDB storage folder
1.  Create new **Type** record
1.  Define type name and identifier

### Environments {#environments}

Environments differentiate translations by context (e.g., "development", "production").

**Create Environment:**

1.  Navigate to TextDB storage folder
1.  Create new **Environment** record
1.  Set environment identifier

## Command Line Interface {#admin-cli-commands}

### Import Command {#import-command}

Import translations from extension language files via CLI. The command scans extensions
for `textdb_import.xlf` and `*.textdb_import.xlf` files in `Resources/Private/Language/`.

```bash
# Import from all installed extensions
vendor/bin/typo3 nr_textdb:import

# Import from a specific extension
vendor/bin/typo3 nr_textdb:import my_extension

# Override existing translations
vendor/bin/typo3 nr_textdb:import my_extension --override
```

**Arguments:**

-   `extensionKey` (optional): Extension key to import from. If omitted, scans all installed extensions.

**Options:**

-   `--override` / `-o`: Override existing translation records.

### Automated Imports {#automated-imports}

Schedule imports via TYPO3 Scheduler:

1.  Navigate to **Scheduler** module
1.  Create new task
1.  Select **Execute console commands**
1.  Choose `nr_textdb:import`
1.  Configure file path and frequency

## Maintenance {#admin-maintenance}

### Database Cleanup {#database-cleanup}

Remove orphaned translations:

```sql
-- Find translations without component
SELECT * FROM tx_nrtextdb_domain_model_translation
WHERE component = 0 OR component NOT IN (
    SELECT uid FROM tx_nrtextdb_domain_model_component
);

-- Delete after verification
DELETE FROM tx_nrtextdb_domain_model_translation
WHERE component = 0 OR component NOT IN (
    SELECT uid FROM tx_nrtextdb_domain_model_component
);
```

### Performance Optimization {#performance-optimization}

**Database Indexes:**

The extension creates appropriate indexes automatically. Verify with:

```sql
SHOW INDEXES FROM tx_nrtextdb_domain_model_translation;
```

### Backup Strategy {#backup-strategy}

**Regular Backups:**

1.  **Database Backup:**

    ```bash
    # Export TextDB tables
    mysqldump -u user -p database \
        tx_nrtextdb_domain_model_translation \
        tx_nrtextdb_domain_model_component \
        tx_nrtextdb_domain_model_type \
        tx_nrtextdb_domain_model_environment \
        > textdb_backup.sql
    ```
1.  **XLIFF Export:**

    -   Use backend module to export all translations
    -   Store XLIFF files in version control
1.  **Automated Backups:**

    -   Schedule via cron or TYPO3 Scheduler
    -   Store backups externally

## Monitoring & Logging {#admin-monitoring}

### Access Logs {#access-logs}

Monitor TextDB module usage via TYPO3 backend logs:

1.  Navigate to **Admin Tools > Log**
1.  Filter by:
     *User actions in TextDB module*
     Translation record changes
    \* Import/export activities

### Error Monitoring {#error-monitoring}

Check for errors:

```bash
# Review TYPO3 logs
tail -f var/log/typo3_*.log | grep nr_textdb
```

### Common Log Entries {#common-log-entries}

```none
# Successful import
[INFO] TextDB: Imported 150 translations from website.xlf

# Failed import
[ERROR] TextDB: Import failed - Invalid XLIFF format

# Auto-creation (if enabled)
[NOTICE] TextDB: Created missing translation: component|type|key
```

## Troubleshooting {#admin-troubleshooting}

### Module Not Accessible {#module-not-accessible}

**Symptoms:** Users cannot see TextDB module

**Solutions:**

1.  Verify module permissions in user group
1.  Clear backend user cache:

    ```bash
    vendor/bin/typo3 cache:flush
    ```
1.  Check module registration:

    ```bash
    vendor/bin/typo3 backend:listmodules
    ```

### Translations Not Appearing {#translations-not-appearing}

**Symptoms:** Frontend shows no translations

**Solutions:**

1.  Verify storage PID configuration
1.  Check translation records exist in correct folder
1.  Flush frontend cache:

    ```bash
    vendor/bin/typo3 cache:flush
    ```
1.  Verify site language configuration

### Import Failures {#import-failures}

**Symptoms:** XLIFF import fails or creates errors

**Solutions:**

1.  Validate XLIFF file format
1.  Check PHP memory limit:

    ```ini
    ; php.ini
    memory_limit = 256M
    upload_max_filesize = 64M
    post_max_size = 64M
    ```
1.  Review error logs for specific issues
1.  Test with minimal XLIFF file first

### Performance Issues {#performance-issues}

**Symptoms:** Slow module loading or search

**Solutions:**

1.  Add database indexes (if missing):

    ```sql
    CREATE INDEX idx_component ON tx_nrtextdb_domain_model_translation (component);
    CREATE INDEX idx_type ON tx_nrtextdb_domain_model_translation (type);
    CREATE INDEX idx_placeholder ON tx_nrtextdb_domain_model_translation (placeholder);
    ```
1.  Optimize database tables:

    ```sql
    OPTIMIZE TABLE tx_nrtextdb_domain_model_translation;
    ```
1.  Increase PHP memory for large datasets

## Migration & Upgrades {#admin-migration}

### Migrating from Other Translation Systems {#migrating-from-other-translation-systems}

**From XLIFF Files:**

1.  Export existing XLIFF files
1.  Convert to TextDB format (adjust `trans-unit` IDs)
1.  Import via backend module

**From Database:**

Create migration script:

```php
// Migration example (adapt getter names to your source system)
$translations = $oldRepository->findAll();
foreach ($translations as $old) {
    $new = new Translation();
    $new->setComponent($componentMapping[$old->getComponent()]);
    $new->setPlaceholder($old->getPlaceholder());
    $new->setValue($old->getValue());
    $translationRepository->add($new);
}
$persistenceManager->persistAll();
```

### Version Updates {#version-updates}

**Pre-Update Checklist:**

1.  ☐ Backup database
1.  ☐ Export all translations
1.  ☐ Review CHANGELOG.md
1.  ☐ Test in development first
1.  ☐ Schedule maintenance window

**Update Process:**

```bash
# 1. Update package
composer update netresearch/nr-textdb

# 2. Update database
vendor/bin/typo3 database:updateschema

# 3. Run upgrade wizards (if any)
vendor/bin/typo3 upgrade:run

# 4. Clear all caches
vendor/bin/typo3 cache:flush

# 5. Verify functionality
# Test import/export and translation display
```

## Integration with Other Extensions {#admin-integration}

### nr-sync Integration {#nr-sync-integration}

If `netresearch/nr-sync` is installed, TextDB includes a sync module:

**Configuration:**

```php
// Automatically registered in Configuration/Backend/Modules.php
'netresearch_sync_textdb' => [
    'parent' => 'netresearch_sync',
    'moduleData' => [
        'dumpFile' => 'nr-textdb.sql',
        'tables' => [
            'tx_nrtextdb_domain_model_component',
            'tx_nrtextdb_domain_model_environment',
            'tx_nrtextdb_domain_model_translation',
            'tx_nrtextdb_domain_model_type',
        ],
    ],
];
```

**Usage:**

Sync TextDB data between environments using the nr-sync module interface.

## Security Considerations {#admin-security}

### Access Control {#access-control}

-   Restrict TextDB module access to trusted users
-   Use separate user groups for editors vs administrators
-   Limit storage folder access via page permissions

### File Upload Security {#file-upload-security}

-   Validate XLIFF file format before processing
-   Implement file size limits
-   Scan uploaded files for malicious content
-   Store uploads in protected directory

### Data Integrity {#data-integrity}

-   Regular database backups
-   Version control for XLIFF exports
-   Audit trail via TYPO3 logging
-   Implement approval workflow for sensitive translations

### SQL Injection Prevention {#sql-injection-prevention}

The extension uses Extbase query API, which provides:

-   Prepared statements
-   Parameter binding
-   SQL injection protection

> [!IMPORTANT]
> Never use raw SQL queries when working with TextDB data!

## Performance Optimization {#admin-performance}

### Database Optimization {#database-optimization}

```sql
-- Analyze table statistics
ANALYZE TABLE tx_nrtextdb_domain_model_translation;

-- Optimize table storage
OPTIMIZE TABLE tx_nrtextdb_domain_model_translation;
```

### Query Optimization {#query-optimization}

Monitor slow queries:

```ini
; php.ini or my.cnf
slow_query_log = 1
long_query_time = 2
```

### Caching Strategy {#caching-strategy}

The extension uses in-memory caching for translation lookups within each request.
For high-traffic sites, ensure TYPO3's page cache is properly configured to cache
rendered pages containing TextDB translations.

## Best Practices {#admin-best-practices}

### Organizational Structure {#organizational-structure}

-   **Separate Folders**: Use dedicated folder per environment if needed
-   **Consistent Naming**: Establish naming conventions for components
-   **Documentation**: Maintain documentation of component/type structure

### Workflow Management {#workflow-management}

-   **Change Control**: Implement approval process for production translations
-   **Testing**: Test translations in staging before production
-   **Rollback Plan**: Keep XLIFF exports for quick rollback

### Monitoring {#monitoring}

-   **Regular Audits**: Review translation usage and orphaned records
-   **Performance Metrics**: Monitor module response times
-   **User Training**: Provide training for editors

### Scalability {#scalability}

-   **Pagination**: Adjust pagination limits for large datasets
-   **Archiving**: Archive old/unused translations
-   **Distribution**: Consider database replication for high-traffic sites