Administrator Manual 

Initial Setup Checklist 

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

Detailed Setup Steps 

1. Create Storage Folder

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

textDbPid = 123
createIfMissing = 1

3. Language Setup

Ensure site languages are configured:

# 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

Backend User Groups 

Create dedicated user groups for TextDB access:

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)

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 

1. Navigate to System > Backend Users > Backend User Groups
2. Create/Edit user group

3. Access Lists tab:

   • Select modules
   • Select table permissions

4. Mounts and Workspaces tab:

   • Add DB Mount to TextDB folder
5. Assign users to the group

Components 

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

Create Component:

1. Go to List module
2. Navigate to TextDB storage folder
3. Click Create new record
4. Select Component
5. Enter component details

Types 

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

Create Type:

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

Environments 

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

Create Environment:

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

Import Command 

Import translations via CLI:

# Import single file
vendor/bin/typo3 nr_textdb:import /path/to/translations.xlf

# Import multiple files
vendor/bin/typo3 nr_textdb:import /path/to/translations/*.xlf

Command Options:

vendor/bin/typo3 nr_textdb:import --help

Automated Imports 

Schedule imports via TYPO3 Scheduler:

1. Navigate to Scheduler module
2. Create new task
3. Select Execute console commands
4. Choose nr_textdb:import
5. Configure file path and frequency

Database Cleanup 

Remove orphaned translations:

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

Database Indexes:

The extension creates appropriate indexes automatically. Verify with:

SHOW INDEXES FROM tx_nrtextdb_domain_model_translation;

Cache Configuration:

Ensure proper cache configuration:

// config/system/additional.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['tx_nrtextdb'] = [
    'backend' => \TYPO3\CMS\Core\Cache\Backend\Typo3DatabaseBackend::class,
    'options' => [
        'defaultLifetime' => 86400, // 24 hours
    ],
];

Backup Strategy 

Regular Backups:

1. Database Backup:

   # 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

   Copied!

2. XLIFF Export:

   • Use backend module to export all translations
   • Store XLIFF files in version control

3. Automated Backups:

   • Schedule via cron or TYPO3 Scheduler
   • Store backups externally

Access Logs 

Monitor TextDB module usage via TYPO3 backend logs:

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

Error Monitoring 

Check for errors:

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

Common Log Entries 

# 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

Module Not Accessible 

Symptoms: Users cannot see TextDB module

Solutions:

1. Verify module permissions in user group

2. Clear backend user cache:

   vendor/bin/typo3 cache:flush

   Copied!

3. Check module registration:

   vendor/bin/typo3 backend:listmodules

   Copied!

Translations Not Appearing 

Symptoms: Frontend shows no translations

Solutions:

1. Verify storage PID configuration
2. Check translation records exist in correct folder

3. Flush frontend cache:

   vendor/bin/typo3 cache:flush

   Copied!
4. Verify site language configuration

Import Failures 

Symptoms: XLIFF import fails or creates errors

Solutions:

1. Validate XLIFF file format

2. Check PHP memory limit:

   ; php.ini
   memory_limit = 256M
   upload_max_filesize = 64M
   post_max_size = 64M

   Copied!
3. Review error logs for specific issues
4. Test with minimal XLIFF file first

Performance Issues 

Symptoms: Slow module loading or search

Solutions:

1. Add database indexes (if missing):

   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);

   Copied!

2. Optimize database tables:

   OPTIMIZE TABLE tx_nrtextdb_domain_model_translation;

   Copied!
3. Increase PHP memory for large datasets

Migrating from Other Translation Systems 

From XLIFF Files:

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

From Database:

Create migration script:

// Migration example
$translations = $oldRepository->findAll();
foreach ($translations as $old) {
    $new = new Translation();
    $new->setComponent($componentMapping[$old->getComponent()]);
    $new->setPlaceholder($old->getKey());
    $new->setValue($old->getTranslation());
    $translationRepository->add($new);
}
$persistenceManager->persistAll();

Version Updates 

Pre-Update Checklist:

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

Update Process:

# 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

nr-sync Integration 

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

Configuration:

// 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.

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 

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

Data Integrity 

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

SQL Injection Prevention 

The extension uses Extbase query API, which provides:

• Prepared statements
• Parameter binding
• SQL injection protection

Database Optimization 

-- Analyze table statistics
ANALYZE TABLE tx_nrtextdb_domain_model_translation;

-- Optimize table storage
OPTIMIZE TABLE tx_nrtextdb_domain_model_translation;

Query Optimization 

Monitor slow queries:

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

Caching Strategy 

Configure appropriate cache lifetime:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations']['tx_nrtextdb'] = [
    'backend' => \TYPO3\CMS\Core\Cache\Backend\RedisBackend::class,
    'options' => [
        'hostname' => 'localhost',
        'database' => 3,
        'defaultLifetime' => 86400,
    ],
];

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 

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

Monitoring 

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

Scalability 

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