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

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)

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)

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
   • Select the excluded fields under Allowed excludefields

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 from extension language files via CLI. The command scans extensions for textdb_import.xlf and *.textdb_import.xlf files in Resources/Private/Language/.

# 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 

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;

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

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 

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.

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