---
title: "Administrator Manual"
manual: "TextDB"
version: "4.1"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-textdb:administrator@4.1"
source: "Administrator/Index.rst"
rendered: "2026-10-31T14:42:22+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

Allowed Excludefields (Translation):
✓ Value
✓ Language, Environment, Component, Type, Placeholder
  (only to add translations in languages that have none yet)

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

Allowed Excludefields:
✓ Translation: Value, Language, Environment, Component, Type, Placeholder
✓ Component, Type, Environment: Name

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

Editors with this setup can list, export and edit translations. Importing XLIFF
files needs modify access to all four tables and the excluded fields listed for
the administrator group, which that group has. The module also applies the
group's language list and refuses changes in a draft workspace that does not
allow live editing; see [Backend Module Configuration](https://docs.typo3.org/permalink/netresearch/nr-textdb:backend-module-configuration@4.1) for what each
action checks.

### 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
    -   Select the excluded fields under **Allowed excludefields**
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.

**Skipped units:**

After each file the command prints one line per kind of unit it left out
or shortened, with the number of units and the keys of the first ten:

-   Units that are not approved (`approved="no"` in XLIFF 1.2, segment
    `state="initial"` or `state="translated"` in XLIFF 2.0) in a
    translation file, while
    `$GLOBALS['TYPO3_CONF_VARS']['LANG']['requireApprovedLocalizations']` is
    enabled, the TYPO3 default. The line names the setting.
-   Plural units of which only some of the first two forms are approved,
    under the same setting. They are imported with the approved forms only.
-   Units without text, for example an untranslated unit without `<target>`
    in an XLIFF 1.2 translation file.

```text
Import translations from file …/de.textdb_import.xlf for language de (1)
Translations not imported because they are not approved and $GLOBALS['TYPO3_CONF_VARS']['LANG']['requireApprovedLocalizations'] is enabled (2): checkout|button|draft, checkout|label|note
Plural translations imported without their forms that are not approved, because $GLOBALS['TYPO3_CONF_VARS']['LANG']['requireApprovedLocalizations'] is enabled (1): checkout|label|items
Translations not imported because they have no text (1): checkout|button|cancel
Imported: 5, Updated: 0
```

A unit of an XLIFF 2.0 translation file without `<target>`, a segment
without `<target>` in an XLIFF 2.0 plural unit, and the third and later
forms of any plural unit are not reported, because TYPO3 drops them while
reading the file. See [Units the Import Skips](https://docs.typo3.org/permalink/netresearch/nr-textdb:import-skipped-units@4.1).

### 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