TextDB is Designed for: Frontend System Strings 

User interface elements that come from your code, NOT editor-created content:

✅ Form labels: "First Name", "Email Address", "Submit Button"

✅ Button texts: "Add to Cart", "Checkout", "Learn More"

✅ Error messages: "Invalid email format", "Field is required"

✅ Navigation labels: "Products", "About Us", "Contact"

✅ Status messages: "Item added to cart", "Order confirmed"

✅ Validation messages, tooltips, placeholder texts

Example Scenario: Your e-commerce checkout has 50+ labels/buttons needing German, French, and Spanish translations. Instead of editing .xlf files, editors manage them through TextDB's backend module.

TextDB is NOT for: 

❌ Page content created by editors (use TYPO3's built-in page translation)

❌ News articles or blog posts (use news/blog extension translation features)

❌ Content elements like text blocks, images (use TYPO3 content localization)

❌ Backend module labels (use TYPO3's core translation system)

❌ TCA field labels (use locallang_db.xlf in your extension)

Translation Scope 

TextDB focuses specifically on Frontend System Strings within the TYPO3 translation landscape:

• Backend/Admin Interface → TYPO3 Core locallang files
• Content Elements → TYPO3 Page/Content translation
• Editor-created content → TYPO3 Localization features
• Frontend System Strings → ✨ TextDB (YOU ARE HERE)

Key Features 

• Backend Translation Editor: Edit translations directly in TYPO3 backend
• Import/Export: Batch import and export translations via XLIFF files
• Multi-language Support: Manage translations for all configured site languages
• Component-Based Organization: Organize translations by components and types
• Environment Support: Different translation sets for different environments
• Command-Line Import: CLI command for automated translation imports
• ViewHelper Integration: Custom ViewHelpers for easy frontend integration
• Filter & Search: Powerful filtering and search capabilities
• Pagination: Efficient handling of large translation sets

Backend Module 

The TextDB backend module provides an intuitive interface for managing translations:

Translation List View

The main list view displays all translations with filtering by component, type, placeholder, and value. Pagination is built in for large datasets.

┌─────────────────────────────────────────────────────────────┐
│  Netresearch TextDB                          [List] [Import]│
├─────────────────────────────────────────────────────────────┤
│  Component: [All        ▼]  Type: [All    ▼]               │
│  Placeholder: [________]    Value: [________]  [🔍 Search] │
├──────┬───────────┬────────┬──────────────┬─────────────────┤
│ Lang │ Component │ Type   │ Placeholder  │ Value           │
├──────┼───────────┼────────┼──────────────┼─────────────────┤
│ 🏴 ▶ │ checkout  │ button │ submit       │ Proceed to Pay  │
│ 🏴 ▶ │ checkout  │ label  │ email        │ Email Address   │
│ 🏴 ▶ │ website   │ label  │ welcome.msg  │ Welcome!        │
└──────┴───────────┴────────┴──────────────┴─────────────────┘
│◀ ◁  Records 1 - 15  Page [1] / 5  ▷ ▶│  🔄

Multi-language Translation Editor

Click the language icons on any row to expand the inline translation editor, showing existing translations and allowing new languages to be added:

┌──────────────────────────────────────────────┐
│  Translation: checkout | button | submit      │
├──────────────────────────────────────────────┤
│ 🇬🇧 English    │ [Proceed to Checkout      ] │
│ 🇩🇪 German     │ [Zur Kasse gehen          ] │
│ 🇫🇷 French     │ [Passer à la caisse       ] │
│ 🇪🇸 Spanish    │ [                         ] │  ← new
├──────────────────────────────────────────────┤
│                              [💾 Save]       │
└──────────────────────────────────────────────┘

Import & Export 

XLIFF Import Interface

Upload XLIFF files to import translations. Optionally override existing values:

┌─────────────────────────────────────────────────┐
│  ℹ️ Upload a textdb XLIFF file to import         │
│     translations into the database.              │
├─────────────────────────────────────────────────┤
│  File: [Choose File...  textdb_import.xlf]       │
│  ☐ Override existing translations                │
│                            [📥 Import]           │
├─────────────────────────────────────────────────┤
│  ✅ Import done for Language: German              │
│  ✅ Translations imported: 42                     │
│  ✅ Translations updated: 15                      │
└─────────────────────────────────────────────────┘

Filtered Export

Export only the translations matching your current filters as a ZIP archive containing XLIFF files for all configured languages.

Use Case 1: Multi-Language E-Commerce Checkout 

Problem: Your checkout flow has 80+ UI strings (field labels, buttons, validation messages) needing translations in German, French, and Spanish.

Without TextDB: Developers edit .xlf files for every text change, deploy to production.

With TextDB: Product managers update translations directly in backend, changes live immediately.

Result: Translation updates in minutes, not days. Non-technical staff manage translations independently.

Use Case 2: SaaS Application with Dynamic Forms 

Problem: Multi-tenant SaaS with 200+ form labels across 15 modules, requiring consistent translation management.

Without TextDB: Scattered .xlf files across multiple extensions, no central overview, duplicate translations.

With TextDB: Hierarchical organization by component/type, centralized filtering, bulk operations, zero duplication.

Result: 70% reduction in translation maintenance time, consistent terminology across modules.

Use Case 3: Agency Managing Multiple Client Sites 

Problem: 20+ TYPO3 installations, each with custom form/button texts needing German/English translations.

Without TextDB: Copy .xlf files between projects, manual sync, version control overhead.

With TextDB: Export/import workflows, standardized translation structure, zero-friction migration via textdb:translate.

Result: Standardized translation process across all clients, 50% faster project setup.

Use Case 4: Government Website Compliance 

Problem: Legal requirements demand audit trails for translated UI strings, editor-friendly workflow without file access.

Without TextDB: Developers as bottleneck for every text change, no change tracking, risky file edits.

With TextDB: Backend module access for translators, database change tracking, missing translation detection.

Result: Compliance-ready audit trails, editor empowerment, reduced developer burden.

Traditional File-Based Approach (Without TextDB) 

File Structure:

Your TYPO3 Project/
├── typo3conf/ext/my_extension/
│   └── Resources/Private/Language/
│       ├── locallang.xlf                    # 150 lines of XML
│       ├── de.locallang.xlf                 # 150 lines (duplicated structure)
│       ├── fr.locallang.xlf                 # 150 lines (duplicated structure)
│       └── locallang_checkout.xlf           # Another 200 lines

Workflow: Developer edits XML → Git commit → Deploy → Cache clear → Test

Problems:

• ❌ Non-developers can't update translations
• ❌ Changes require full deployment cycle
• ❌ No central overview of all translations
• ❌ Duplicate structure across language files
• ❌ Merge conflicts in XML files
• ❌ No built-in search/filter capabilities

Database-Backed Approach (With TextDB) 

Backend Interface:

Your TYPO3 Backend/
└── Netresearch → TextDB Module
    ├── 🔍 Search: [button checkout]          # Instant filtering
    ├── 📊 Filter: Component: "checkout" | Type: "button"
    │
    ├── ✏️ Edit inline:
    │   ├── EN: "Proceed to Checkout"  →  [Click to edit]
    │   ├── DE: "Zur Kasse gehen"      →  [Click to edit]
    │   └── FR: "Passer à la caisse"   →  [Click to edit]
    │
    ├── 📥 Import: Upload XLF → Auto-merge
    └── 📤 Export: Download ZIP (all languages)

Workflow: Editor logs in → Click translation → Edit → Save → Live immediately

Benefits:

• ✅ Non-developers manage translations independently
• ✅ Changes live in seconds (no deployment)
• ✅ Centralized dashboard with 500+ translations
• ✅ Single source of truth (no XML duplication)
• ✅ Advanced filtering: component, type, placeholder, value search
• ✅ Export/import for translation agencies
• ✅ Zero-friction migration via textdb:translate ViewHelper

Migration Path: Zero Disruption 

Phase 1: Prepare (5 minutes)

Add namespace to your templates:

xmlns:textdb="http://typo3.org/ns/Netresearch/NrTextdb/ViewHelpers"

Phase 2: Auto-Import (Automatic)

Replace f:translate with textdb:translate:

<textdb:translate key="LLL:EXT:my_ext/Resources/Private/Language/locallang.xlf:submit" />

First render automatically imports to database. All existing translations preserved.

Phase 3: Optimize (Gradual)

Switch to native syntax at your own pace:

<textdb:textdb component="checkout" type="button" placeholder="submit" />

Old .xlf files can stay as backup until you're confident.

Zero Downtime: Existing translations continue working during migration.

Zero Data Loss: Automatic import preserves all language variants.

Zero Risk: Rollback anytime by reverting ViewHelper change.

Key Differentiators 

1. Zero-Friction Migration Drop-in replacement for f:translate ViewHelper with automatic LLL import on first render. No manual migration required.
2. Hierarchical Organization 4-level structure (Environment → Component → Type → Placeholder) prevents chaos at scale. Manage 500+ translations logically instead of flat key-value pairs.

3. Non-Developer Empowerment Product managers, translators, and editors update translations without:

   • File system access
   • Git knowledge
   • Deployment pipelines
   • Developer intervention

4. Production-Grade Quality

   • PHPStan level 10 static analysis
   • 95%+ test coverage
   • PSR-12 coding standards
   • Modern PHP 8.2+ features (readonly properties, constructor promotion)
   • Comprehensive CI/CD pipeline

5. Developer Experience

   • Modern architecture with dependency injection
   • CLI automation with console commands
   • API-ready with clean service layer
   • Token-optimized for AI-assisted development

Competitive Positioning 

vs. l10nmgr: TextDB focuses on frontend system strings with simpler workflows, while l10nmgr targets complex workflow-heavy translation management.

vs. Snowbabel: TextDB provides advanced filtering, hierarchical organization, and production-grade code quality beyond Snowbabel's basic editing.

vs. translatelabels: TextDB offers zero-friction migration and modern TYPO3 v13 support, while translatelabels is unmaintained.

vs. TYPO3 Core: TextDB provides backend module access and live updates, while TYPO3 Core requires file editing and deployment cycles.

Minimum Requirements 

• TYPO3: 13.4.0 or higher
• PHP: 8.2, 8.3, or 8.4

• PHP Extensions:

  • ext-zip
  • ext-simplexml
  • ext-libxml

Recommended 

• Database: MariaDB 10.11+ or MySQL 8.0+
• Development: DDEV or Docker for local development

From Version 2.x to 3.x 

Version 3.0 brings TYPO3 13.4 LTS compatibility:

Breaking Changes:

• PHP 8.2 minimum requirement
• TYPO3 13.4 minimum requirement
• Database schema updates required

Migration Steps:

1. Ensure PHP 8.2+ is installed

2. Update composer dependencies:

   composer update netresearch/nr-textdb

   Copied!

3. Update database schema:

   vendor/bin/typo3 database:updateschema

   Copied!

4. Clear all caches:

   vendor/bin/typo3 cache:flush

   Copied!
5. Test translation functionality in backend module

Extension not visible after installation 

• Clear all caches via Admin Tools > Maintenance > Flush TYPO3 and PHP Cache
• Verify extension is activated in Extension Manager
• Check that database tables were created

Missing translations 

• Verify storage PID is configured correctly in Extension Configuration
• Check that translations are stored in the correct page/folder
• Ensure "Create if missing" option is enabled (if desired)

Import fails 

• Verify XLIFF file format matches expected structure
• Check file permissions on upload
• Review logs in Admin Tools > Log
• Ensure PHP extensions (ext-zip, ext-simplexml, ext-libxml) are installed

Available Settings 

Constants 

The extension provides the following TypoScript constants:

# File: Configuration/TypoScript/constants.typoscript
module.tx_nrtextdb {
    persistence {
        # Default storage PID
        storagePid =
    }
}

Setup 

The extension setup configures the backend module with pagination:

# File: Configuration/TypoScript/setup.typoscript
module.tx_nrtextdb {
    settings {
        pagination {
            enablePagination = 1
            itemsPerPage = 15
        }
    }
}

Access Control 

The TextDB backend module requires appropriate permissions:

Module Access:

1. Navigate to System > Backend Users > [User Group]
2. Go to tab Access Lists
3. Under Modules, check: Netresearch Netresearch TextDB

Record Permissions:

Grant access to TextDB tables:

• tx_nrtextdb_domain_model_translation
• tx_nrtextdb_domain_model_component
• tx_nrtextdb_domain_model_type
• tx_nrtextdb_domain_model_environment

Module Customization 

The backend module is configured in Configuration/Backend/Modules.php:

// Parent module (Netresearch)
'netresearch_module' => [
    'labels' => 'LLL:EXT:nr_textdb/Resources/Private/Language/locallang_mod.xlf',
    'iconIdentifier' => 'extension-netresearch-module',
    'position' => ['after' => 'web'],
],

// TextDB submodule
'netresearch_textdb' => [
    'parent' => 'netresearch_module',
    'access' => 'user',
    'iconIdentifier' => 'extension-netresearch-textdb',
    'path' => '/module/netresearch/textdb',
    'labels' => 'LLL:EXT:nr_textdb/Resources/Private/Language/locallang_mod_textdb.xlf',
    'extensionName' => 'NrTextdb',
    'controllerActions' => [
        TranslationController::class => [
            'list', 'translated', 'translateRecord',
            'import', 'export',
        ],
    ],
],

Dependency Injection 

Services are configured in Configuration/Services.yaml:

services:
    _defaults:
        autowire: true
        autoconfigure: true
        public: false

    Netresearch\NrTextdb\:
        resource: '../Classes/*'
        exclude: '../Classes/Domain/Model/*'

    # Public services
    Netresearch\NrTextdb\Service\TranslationService:
        public: true

    # Console commands
    Netresearch\NrTextdb\Command\ImportCommand:
        tags:
            - name: 'console.command'
              command: 'nr_textdb:import'
              description: 'Imports textdb records from language files'
              schedulable: false

Table Configuration (TCA) 

The extension defines TCA for four tables:

// Configuration/TCA/tx_nrtextdb_domain_model_translation.php
return [
    'ctrl' => [
        'title' => 'LLL:EXT:nr_textdb/Resources/Private/Language/locallang_db.xlf:tx_nrtextdb_domain_model_translation',
        'label' => 'placeholder',
        'languageField' => 'sys_language_uid',
        'transOrigPointerField' => 'l10n_parent',
        'searchFields' => 'value,placeholder',
        // ... additional configuration
    ],
    'columns' => [
        'value' => [
            'label' => 'Translation Value',
            'config' => [
                'type' => 'text',
                'required' => true,
            ],
        ],
        // ... additional fields
    ],
];

Storage Configuration 

Recommended Setup:

1. Create a dedicated storage folder at root level
2. Set folder type to "Folder"
3. Configure folder PID in extension configuration
4. Create language overlays for this folder

Page Tree:
└── [Root]
    └── TextDB Translations (Folder, PID: 123)
        ├── [Default Language]
        └── [Language Overlays]

Adding Custom Translations 

To add support for additional languages:

1. Copy locallang.xlf to [lang-key].locallang.xlf
2. Update the target-language attribute
3. Translate all <target> elements

Custom ViewHelper Configuration 

When using the TextDB ViewHelper in your templates:

{namespace textdb=Netresearch\NrTextdb\ViewHelpers}

<textdb:textdb
    component="my-component"
    type="label"
    placeholder="welcome.message"
/>

JavaScript Module Configuration 

The extension provides JavaScript modules via Configuration/JavaScriptModules.php:

return [
    'dependencies' => ['core', 'backend'],
    'imports' => [
        '@netresearch/nr-textdb/' => 'EXT:nr_textdb/Resources/Public/JavaScript/',
    ],
];

Development Environment 

// config/system/additional.php (Development)
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb'] = [
    'textDbPid' => 123,
    'createIfMissing' => true,
];

Production Environment 

// config/system/additional.php (Production)
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb'] = [
    'textDbPid' => 456,
    'createIfMissing' => false, // Strict mode
];

List View 

The main list view displays all translation records:

• Placeholder: The translation key/identifier
• Value: The translated text
• Component: The component this translation belongs to
• Type: The translation type (label, message, etc.)
• Environment: Target environment (if applicable)
• Language: The language of the translation

Pagination 

Large translation sets are automatically paginated:

• Use the pagination controls at the bottom
• Adjust items per page if needed
• Navigate between pages efficiently

Component Filter 

Select a specific component to show only its translations:

1. Click the Component dropdown
2. Select the desired component
3. The list updates automatically

Type Filter 

Filter by translation type:

1. Click the Type dropdown
2. Select label, message, or other types
3. View filtered results

Search 

Search for specific translations:

1. Enter search term in the search box
2. Search applies to: Placeholder (key) Translation value
3. Press Enter or click Search

Edit Single Translation 

1. Click the pencil icon next to a translation
2. Modify the translation value
3. Update other fields if needed: Component assignment Type assignment * Environment
4. Click Save

Multi-Language Editing 

To edit translations in different languages:

1. Switch the language in the TYPO3 toolbar
2. Edit the translation for that language
3. Repeat for additional languages

Import from XLIFF File 

1. Click the Import button in the toolbar
2. Select the XLIFF file to import

3. Choose import options:

   • Overwrite Existing: Check to replace existing translations
   • Leave unchecked to only import new translations
4. Click Import
5. Review the import summary

Expected File Format 

English Source File (en):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<xliff version="1.0">
    <file source-language="en" datatype="plaintext" original="messages">
        <header>
            <authorName>Your Name</authorName>
            <authorEmail>you@example.com</authorEmail>
        </header>
        <body>
            <trans-unit id="component|type|placeholder">
                <source>Translation value</source>
            </trans-unit>
        </body>
    </file>
</xliff>

Translated File (e.g., German):

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<xliff version="1.0">
    <file source-language="en" target-language="de" datatype="plaintext" original="messages">
        <header>
            <authorName>Your Name</authorName>
            <authorEmail>you@example.com</authorEmail>
        </header>
        <body>
            <trans-unit id="component|type|placeholder">
                <target>Übersetzungswert</target>
            </trans-unit>
        </body>
    </file>
</xliff>

Export Filtered Translations 

1. Apply desired filters (component, type, search)
2. Click Export with current filter
3. The system exports: All translations matching current filters All languages * Ignores pagination
4. Save the XLIFF file to your computer

Use Cases for Export 

• External Translation: Send to translation agency
• Backup: Create snapshots of translations
• Migration: Move translations between TYPO3 instances
• Review: Share with stakeholders for review

Typical Workflow 

1. Developer creates placeholder translations
2. Editor reviews and refines translations

3. Translator (if needed):

   1. Editor exports current translations
   2. Translator works on XLIFF file
   3. Editor imports translated file
4. Editor verifies imported translations
5. Translations are immediately available on frontend

Best Practices 

• Consistent Naming: Use clear, descriptive placeholders
• Component Organization: Group related translations
• Regular Backups: Export translations periodically
• Language Review: Have native speakers review translations
• Testing: Verify translations on frontend after changes

Translation Not Showing 

• Check Language: Ensure correct language is selected
• Verify Filters: Clear all filters to see all translations
• Refresh Cache: Ask administrator to clear frontend cache

Import Failed 

• File Format: Verify XLIFF file format is correct
• File Naming: Check file name follows convention
• Permissions: Contact administrator if upload fails
• File Size: Large files may timeout - split into smaller files

Cannot Edit Translation 

• Permissions: Contact administrator for access rights
• Lock Status: Another user may be editing - wait and retry
• Language Access: Verify you have access to that language

Quick Search 

Use the search box to quickly locate translations by partial matches.

Bulk Operations 

For bulk changes, consider exporting, editing in a text editor, and re-importing.

Favorites 

Bookmark frequently used filter combinations in your browser.

Translation Preview 

Keep a frontend tab open to immediately verify translation changes.

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

Domain Model 

The extension uses Extbase domain-driven design:

Domain Models:
├── Translation      # Main translation record
├── Component        # Logical grouping (website, shop, etc.)
├── Type             # Category (label, message, error)
└── Environment      # Context (dev, staging, production)

Repositories:
├── TranslationRepository
├── ComponentRepository
├── TypeRepository
└── EnvironmentRepository

Services:
├── TranslationService  # Core translation logic
└── ImportService       # XLIFF import handling

Controllers:
└── TranslationController  # Backend module

Dependency Injection 

All services use constructor injection via Configuration/Services.yaml:

services:
    _defaults:
        autowire: true
        autoconfigure: true
        public: false

    Netresearch\NrTextdb\:
        resource: '../Classes/*'
        exclude: '../Classes/Domain/Model/*'

Supported Languages 

European (13): Afrikaans (af), Czech (cs), Danish (da), German (de), Spanish (es), Finnish (fi), French (fr), Italian (it), Dutch (nl), Norwegian (no), Polish (pl), Portuguese (pt), Swedish (sv)

Asian & African (10): Arabic (ar), Hindi (hi), Indonesian (id), Japanese (ja), Korean (ko), Russian (ru), Swahili (sw), Thai (th), Vietnamese (vi), Chinese (zh)

Technical Implementation 

XLIFF 1.2 Standard

All translation files follow XLIFF 1.2 specification:

<?xml version="1.0" encoding="utf-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" datatype="plaintext" original="EXT:nr_textdb/Resources/Private/Language/locallang.xlf" date="..." product-name="nr_textdb">
        <header/>
        <body>
            <trans-unit id="module.title" resname="module.title" translate="no">
                <source>Netresearch</source>
            </trans-unit>
        </body>
    </file>
</xliff>

Proper Names Protection

Brand names are marked as untranslatable using translate="no" attribute:

<trans-unit id="module.title" resname="module.title" translate="no">
    <source>Netresearch</source>
</trans-unit>

This ensures "Netresearch" and "TextDb" remain unchanged across all translations.

UTF-8 Encoding

All language files use UTF-8 encoding to support non-Latin scripts:

• Right-to-left scripts: Arabic (العربية)
• Asian ideographs: Chinese (中文), Japanese (日本語), Korean (한국어)
• Indic scripts: Hindi (हिन्दी), Thai (ไทย)

File Structure 

Each language has 5 translation files:

Resources/Private/Language/
├── {lang}.locallang.xlf           # General interface labels
├── {lang}.locallang_db.xlf        # Database field labels
├── {lang}.locallang_mod.xlf       # Backend module labels
├── {lang}.locallang_mod_sync.xlf  # Sync module labels
└── {lang}.locallang_mod_textdb.xlf # TextDB module labels

Total: 116 XLIFF files (23 languages × 5 files + 1 source file per type)

Community Translation Workflow 

The extension integrates with TYPO3's centralized Crowdin translation system:

Configuration (crowdin.yml):

files:
  - source: Resources/Private/Language/locallang.xlf
    translation: Resources/Private/Language/%two_letters_code%.locallang.xlf
  - source: Resources/Private/Language/locallang_db.xlf
    translation: Resources/Private/Language/%two_letters_code%.locallang_db.xlf
  # ... additional file types

Translation Process:

1. Translators contribute via https://crowdin.com/project/typo3-cms
2. TYPO3 translation coordinators review submissions
3. Approved translations automatically sync to repository
4. Changes included in next extension release

Adding New Languages:

To add a new language:

1. Create language files following naming convention: {lang}.locallang*.xlf
2. Copy structure from English source files
3. Update crowdin.yml with new language patterns
4. Submit to Crowdin for community translation

See CONTRIBUTING.md for detailed translation contribution guidelines.

TextDB ViewHelper 

class TextdbViewHelper

Main ViewHelper for displaying translations in Fluid templates.

Namespace

Netresearch\NrTextdb\ViewHelpers

Extends

TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper

Usage:

{namespace textdb=Netresearch\NrTextdb\ViewHelpers}

<textdb:textdb
    component="website"
    type="label"
    placeholder="welcome.message"
/>

Copied!

Parameters:

component

component

Type

string

Required

true

Component identifier for organizing translations (e.g., "website", "shop", "checkout").

type

type

Type

string

Required

true

Default

P

Type identifier categorizing the translation (e.g., "label", "message", "error", "button").

placeholder

placeholder

Type

string

Required

true

Unique translation key within the component and type context.

environment

environment

Type

string

Required

false

Default

default

Environment name for contextual translations.

Output:

Returns the translated text for the current page language.

Example:

<!-- Simple usage -->
<h1><textdb:textdb component="website" type="label" placeholder="page.title" /></h1>

<!-- With explicit environment -->
<p>
    <textdb:textdb
        component="website"
        type="message"
        placeholder="welcome.text"
        environment="production"
    />
</p>

<!-- Inline syntax -->
{textdb:textdb(component: 'website', type: 'label', placeholder: 'button.submit')}

Translate ViewHelper 

Alternative ViewHelper compatible with f:translate interface.

Usage:

{namespace textdb=Netresearch\NrTextdb\ViewHelpers}

<textdb:translate key="LLL:EXT:my_ext:path.to.key" />

Component Configuration:

Set component in controller:

use Netresearch\NrTextdb\ViewHelpers\TranslateViewHelper;

class MyController extends ActionController
{
    public function initializeAction(): void
    {
        TranslateViewHelper::$component = 'my-component';
    }
}

Auto-Import Feature:

When enabled (createIfMissing = 1), this ViewHelper will:

1. Load translation from XLIFF file on first request
2. Create TextDB record automatically
3. Use TextDB record on subsequent requests

TranslationService 

class TranslationService

Core service for translation management and retrieval.

Namespace

Netresearch\NrTextdb\Service

Dependency Injection:

use Netresearch\NrTextdb\Service\TranslationService;

class MyClass
{
    public function __construct(
        private readonly TranslationService $translationService
    ) {}
}

Copied!

Methods:

translate()            

public function translate(
    string $placeholder,
    string $typeName,
    string $componentName,
    string $environmentName,
): string

Copied!

Retrieves a translated string from the database. If createIfMissing is enabled and the translation doesn't exist, it will be auto-created with a placeholder value.

param string $placeholder

Translation key

param string $typeName

Type name (e.g., "label", "button")

param string $componentName

Component name (e.g., "website", "checkout")

param string $environmentName

Environment name (e.g., "default")

returns

The translated value, or the placeholder if not found

Example:

$value = $this->translationService->translate(
    placeholder: 'welcome.message',
    typeName: 'label',
    componentName: 'website',
    environmentName: 'default',
);

Copied!

createTranslation()                     

public function createTranslation(
    Environment $environment,
    Component $component,
    Type $type,
    string $placeholder,
    int $sysLanguageUid = 0,
    string $value = '',
): Translation

Copied!

Creates a new translation record in the database.

Example:

$translation = $this->translationService->createTranslation(
    environment: $environment,
    component: $component,
    type: $type,
    placeholder: 'cart.add',
    sysLanguageUid: 0,
    value: 'Add to cart',
);

Copied!

getAllLanguages()                  

public function getAllLanguages(): array

Copied!

Returns all configured site languages from the first available site.

returns

Array of SiteLanguage objects

ImportService 

Service for importing XLIFF files.

Injection:

use Netresearch\NrTextdb\Service\ImportService;

public function __construct(
    private readonly ImportService $importService
) {}

Methods:

public function importFile(
    string $file,
    bool $forceUpdate,
    int &$imported,
    int &$updated,
    array &$errors,
): void

$imported = 0;
$updated  = 0;
$errors   = [];

$this->importService->importFile(
    file: '/path/to/translations.xlf',
    forceUpdate: true,
    imported: $imported,
    updated: $updated,
    errors: $errors,
);

echo "Imported: {$imported}, Updated: {$updated}";

public function importEntry(
    int $languageUid,
    ?string $componentName,
    ?string $typeName,
    string $placeholder,
    string $value,
    bool $forceUpdate,
    int &$imported,
    int &$updated,
    array &$errors,
): void

TranslationRepository 

Repository for translation records.

Custom Methods:

public function findAllByComponentTypePlaceholderValueAndLanguage(
    int $component = 0,
    int $type = 0,
    ?string $placeholder = null,
    ?string $value = null,
    int $languageId = 0,
): QueryResultInterface

public function findByEnvironmentComponentTypePlaceholderAndLanguage(
    Environment $environment,
    Component $component,
    Type $type,
    string $placeholder,
    int $languageUid,
): ?Translation

public function findByEnvironmentComponentTypeAndPlaceholder(
    Environment $environment,
    Component $component,
    Type $type,
    string $placeholder,
): ?Translation

use Netresearch\NrTextdb\Domain\Repository\TranslationRepository;

public function __construct(
    private readonly TranslationRepository $repository
) {}

public function myAction(): void
{
    $translations = $this->repository
        ->findAllByComponentTypePlaceholderValueAndLanguage(
            component: $componentUid,
            type: $typeUid,
        );

    foreach ($translations as $translation) {
        // Process translations
    }
}

Translation Model 

Main translation entity.

Properties:

class Translation extends AbstractEntity
{
    protected string $placeholder = '';
    protected string $value = '';
    protected ?Component $component = null;
    protected ?Type $type = null;
    protected ?Environment $environment = null;
    protected int $sysLanguageUid = 0;
}

Getters/Setters:

$translation = new Translation();
$translation->setPlaceholder('welcome.message');
$translation->setValue('Welcome!');
$translation->setComponent($component);
$translation->setType($type);

echo $translation->getValue(); // "Welcome!"

Component Model 

class Component extends AbstractValueObject
{
    protected string $name = '';
}

Type Model 

class Type extends AbstractValueObject
{
    protected string $name = '';
}

Environment Model 

class Environment extends AbstractValueObject
{
    protected string $name = '';
}

ImportCommand 

CLI command for importing translations.

Location: Classes/Command/ImportCommand.php

Usage:

vendor/bin/typo3 nr_textdb:import [extensionKey] [--override|-o]

Configuration:

# Configuration/Services.yaml
Netresearch\NrTextdb\Command\ImportCommand:
    tags:
        - name: 'console.command'
          command: 'nr_textdb:import'
          description: 'Imports textdb records from language files'
          schedulable: false

Creating Custom Commands:

namespace MyVendor\MyExt\Command;

use Netresearch\NrTextdb\Service\ImportService;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class CustomImportCommand extends Command
{
    public function __construct(
        private readonly ImportService $importService
    ) {
        parent::__construct();
    }

    protected function execute(
        InputInterface $input,
        OutputInterface $output
    ): int {
        $files = glob('/path/to/translations/*.xlf');

        foreach ($files as $file) {
            $imported = 0;
            $updated = 0;
            $errors = [];
            $this->importService->importFile($file, false, $imported, $updated, $errors);
            $output->writeln("Imported: {$imported}, Updated: {$updated} from {$file}");
        }

        return Command::SUCCESS;
    }
}

Example 1: Programmatic Translation Management 

use Netresearch\NrTextdb\Domain\Model\Translation;
use Netresearch\NrTextdb\Domain\Repository\TranslationRepository;
use Netresearch\NrTextdb\Domain\Repository\ComponentRepository;
use Netresearch\NrTextdb\Domain\Repository\TypeRepository;
use TYPO3\CMS\Extbase\Persistence\Generic\PersistenceManager;

class TranslationManager
{
    public function __construct(
        private readonly TranslationRepository $translationRepository,
        private readonly ComponentRepository $componentRepository,
        private readonly TypeRepository $typeRepository,
        private readonly PersistenceManager $persistenceManager
    ) {}

    public function createBulkTranslations(array $data): void
    {
        $component = $this->componentRepository->findByName('website');
        $type = $this->typeRepository->findByName('label');

        foreach ($data as $key => $value) {
            $translation = new Translation();
            $translation->setPlaceholder($key);
            $translation->setValue($value);
            $translation->setComponent($component);
            $translation->setType($type);

            $this->translationRepository->add($translation);
        }

        $this->persistenceManager->persistAll();
    }
}

Example 2: Custom Export Functionality 

use Netresearch\NrTextdb\Domain\Repository\TranslationRepository;

class CustomExporter
{
    public function __construct(
        private readonly TranslationRepository $repository
    ) {}

    public function exportToJson(int $componentUid): string
    {
        $translations = $this->repository->findAllByComponentTypePlaceholderValueAndLanguage(component: $componentUid);

        $data = [];
        foreach ($translations as $translation) {
            $data[$translation->getPlaceholder()] = $translation->getValue();
        }

        return json_encode($data, JSON_PRETTY_PRINT);
    }

    public function exportToCsv(int $componentUid): string
    {
        $translations = $this->repository->findAllByComponentTypePlaceholderValueAndLanguage(component: $componentUid);

        $csv = "Placeholder,Value,Language\n";
        foreach ($translations as $translation) {
            $csv .= sprintf(
                "%s,%s,%d\n",
                $translation->getPlaceholder(),
                $translation->getValue(),
                $translation->getSysLanguageUid()
            );
        }

        return $csv;
    }
}

Example 3: Frontend Integration 

use Netresearch\NrTextdb\Service\TranslationService;
use TYPO3\CMS\Core\Context\Context;

class FrontendTranslations
{
    public function __construct(
        private readonly TranslationService $translationService,
        private readonly Context $context
    ) {}

    public function getTranslatedMenu(array $menuItems): array
    {
        $languageUid = $this->context->getPropertyFromAspect(
            'language',
            'id'
        );

        foreach ($menuItems as &$item) {
            $item['title'] = $this->translationService->translate(
                placeholder: $item['key'],
                typeName: 'label',
                componentName: 'menu',
                environmentName: 'default',
            );
        }

        return $menuItems;
    }
}

Unit Testing 

Example unit test for Translation model:

namespace Netresearch\NrTextdb\Tests\Unit\Domain\Model;

use Netresearch\NrTextdb\Domain\Model\Translation;
use PHPUnit\Framework\Attributes\CoversClass;
use PHPUnit\Framework\Attributes\Test;
use TYPO3\TestingFramework\Core\Unit\UnitTestCase;

#[CoversClass(Translation::class)]
final class TranslationTest extends UnitTestCase
{
    private Translation $subject;

    protected function setUp(): void
    {
        parent::setUp();
        $this->subject = new Translation();
    }

    #[Test]
    public function setValueSetsValue(): void
    {
        $value = 'Test translation';
        $this->subject->setValue($value);

        self::assertSame($value, $this->subject->getValue());
    }
}

Functional Testing 

Example functional test for repository:

namespace Netresearch\NrTextdb\Tests\Functional\Domain\Repository;

use Netresearch\NrTextdb\Domain\Repository\TranslationRepository;
use TYPO3\TestingFramework\Core\Functional\FunctionalTestCase;

final class TranslationRepositoryTest extends FunctionalTestCase
{
    protected array $testExtensionsToLoad = [
        'typo3conf/ext/nr_textdb',
    ];

    private TranslationRepository $subject;

    protected function setUp(): void
    {
        parent::setUp();
        $this->subject = $this->get(TranslationRepository::class);
        $this->importCSVDataSet(__DIR__ . '/Fixtures/translations.csv');
    }

    public function testFindAllReturnsAllTranslations(): void
    {
        $result = $this->subject->findAll();
        self::assertCount(10, $result);
    }
}

Extending the TranslationService 

namespace MyVendor\MyExt\Service;

use Netresearch\NrTextdb\Service\TranslationService;

class ExtendedTranslationService extends TranslationService
{
    public function translate(
        string $placeholder,
        string $typeName,
        string $componentName,
        string $environmentName,
    ): string {
        // Add custom caching
        $cacheKey = "{$componentName}_{$typeName}_{$placeholder}_{$environmentName}";
        if ($cached = $this->cache->get($cacheKey)) {
            return $cached;
        }

        $result = parent::translate(
            $placeholder,
            $typeName,
            $componentName,
            $environmentName,
        );

        $this->cache->set($cacheKey, $result);
        return $result;
    }
}

Custom ViewHelper 

namespace MyVendor\MyExt\ViewHelpers;

use Netresearch\NrTextdb\Service\TranslationService;
use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;

class CustomTranslateViewHelper extends AbstractViewHelper
{
    public function __construct(
        private readonly TranslationService $translationService
    ) {}

    public function initializeArguments(): void
    {
        $this->registerArgument('key', 'string', 'Translation key', true);
    }

    public function render(): string
    {
        $parts = explode('.', $this->arguments['key']);
        $component = $parts[0] ?? 'default';
        $placeholder = $parts[1] ?? $this->arguments['key'];

        return $this->translationService->translate(
            placeholder: $placeholder,
            typeName: 'label',
            componentName: $component,
            environmentName: 'default',
        );
    }
}

Naming Conventions 

Components:

• Use lowercase with hyphens: website, shop-cart, user-portal
• Be descriptive and consistent

Types:

• Standard types: label, message, error, notification
• Use singular form: button not buttons

Placeholders:

• Use dot notation: page.title, button.submit, error.validation.email
• Be hierarchical and descriptive

Performance 

• Cache translation lookups in frontend
• Use repository methods instead of manual queries
• Batch import/export operations for large datasets
• Consider Redis/Memcached for high-traffic sites

Code Quality 

• Use strict types: declare(strict_types=1)
• Type-hint all parameters and return values
• Write unit tests for business logic
• Document public APIs with PHPDoc

Security 

• Escape translation output in templates: {translation -> f:format.htmlspecialchars()}
• Validate XLIFF files before import
• Use prepared statements (Extbase does this automatically)
• Restrict file upload permissions

ViewHelper Not Working 

// Check namespace registration
{namespace textdb=Netresearch\NrTextdb\ViewHelpers}

// Verify storage PID configuration
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb']['textDbPid']

Service Injection Failing 

# Ensure Services.yaml is configured
services:
    _defaults:
        autowire: true

    MyVendor\MyExt\MyClass:
        public: true  # If accessed via GeneralUtility::makeInstance

Translation Not Found 

// Debug translation lookup
$value = $this->translationService->translate(
    placeholder: 'test.key',
    typeName: 'label',
    componentName: 'website',
    environmentName: 'default',
);

// If $value equals the placeholder, the translation was not found.
// Check:
// - Component 'website' exists in the configured storage folder?
// - Type 'label' exists?
// - Environment 'default' exists?
// - createIfMissing enabled in extension configuration?

TYPO3 Version Support 

• Minimum TYPO3: 13.4.0
• Earlier versions: Not supported (use version 2.x for TYPO3 12)

PHP Version Requirements 

• Minimum PHP: 8.2
• Earlier PHP versions: Not supported

Import Performance 

Issue: Large XLIFF files (>10MB) may timeout during import

Workaround:

• Split large files into smaller chunks

• Increase PHP max_execution_time:

  max_execution_time = 300

  Copied!
• Use CLI import command instead of backend module

Status: Under investigation

GitHub Issue: #30

Language Fallback 

Issue: No automatic fallback to default language if translation missing

Workaround:

• Enable createIfMissing to auto-create translations
• Manually ensure all languages have translations
• Use default parameter in ViewHelpers

Status: Feature request for 3.2.0

GitHub Issue: #32

Extension Conflicts 

No known conflicts with other TYPO3 extensions.

If you experience issues, please:

1. Disable other extensions temporarily
2. Test TextDB functionality
3. Re-enable extensions one by one
4. Report findings to: https://github.com/netresearch/t3x-nr-textdb/issues

Database Engines 

Tested:

• MariaDB 10.11+
• MySQL 8.0+

Not tested:

• PostgreSQL
• SQLite

Note: PostgreSQL and SQLite may work but are not officially supported.

GitHub Issue: #26

Backend Module 

The TextDB backend module is tested with:

• ✅ Chrome/Chromium (latest)
• ✅ Firefox (latest)
• ✅ Safari (latest)
• ✅ Edge (Chromium-based)
• ⚠️ Internet Explorer (not supported)

Problem: Module Not Visible 

Symptoms:

• TextDB module doesn't appear in backend menu
• User has correct permissions

Solution:

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

# Rebuild backend modules
vendor/bin/typo3 backend:listmodules

# Check module registration
ls -la typo3conf/ext/nr_textdb/Configuration/Backend/Modules.php

Problem: Translations Not Updating 

Symptoms:

• Changes in backend don't reflect on frontend
• Old translations still showing

Solution:

# Clear frontend page cache
vendor/bin/typo3 cache:flush

# Clear specific page cache via backend:
# Page > Clear Cache > Clear cache for this page

# Verify correct storage PID in extension configuration

Problem: Import Fails Silently 

Symptoms:

• Import appears to complete but no records created
• No error messages shown

Solution:

1. Check TYPO3 logs:

   tail -f var/log/typo3_*.log

   Copied!

2. Verify XLIFF format:

   <?xml version="1.0" encoding="utf-8"?>
   <xliff version="1.0">
       <file source-language="en" datatype="plaintext" original="messages">
           <body>
               <trans-unit id="component|type|placeholder">
                   <source>Value</source>
               </trans-unit>
           </body>
       </file>
   </xliff>

   Copied!

3. Check file permissions:

   ls -la /path/to/upload/directory

   Copied!

4. Validate XML:

   xmllint --noout yourfile.xlf

   Copied!

Problem: Memory Exhaustion on Export 

Symptoms:

• Export fails with memory limit error
• Large datasets cause timeout

Solution:

1. Increase PHP memory limit temporarily:

   ; php.ini
   memory_limit = 512M

   Copied!
2. Export smaller subsets using filters
3. Use filters to reduce the export dataset to manageable sizes

Community Support 

• GitHub Discussions: https://github.com/netresearch/t3x-nr-textdb/discussions
• Issue Tracker: https://github.com/netresearch/t3x-nr-textdb/issues

Professional Support 

For commercial support and custom development:

• Company: Netresearch DTT GmbH
• Website: https://www.netresearch.de/
• Email: Contact via GitHub issues

Version 3.1.0 

• Performance optimizations for large datasets
• Enhanced import/export UI with progress indicators
• Batch operations for bulk translation management
• Advanced filtering options

GitHub Issue: #33

Version 3.2.0 

• PSR-14 events for extensibility
• Language fallback chain support
• Translation versioning and history
• REST API for external integrations

GitHub Issue: #34

Version 4.0.0 

• TYPO3 14 LTS compatibility
• AI-assisted translation suggestions
• Translation memory integration
• Workflow management with approval process

GitHub Issue: #35

TYPO3 12 LTS Support 

Version 2.x series supports TYPO3 12 LTS.

For details, see the 2.x branch.

Legacy Versions 

Version 1.x series supports TYPO3 10-11.

Note: No longer maintained. Upgrade to 3.x recommended.

3.0.x Series 

Focus: TYPO3 13 LTS support and modernization

Key Improvements:

• Modern PHP 8.2+ features
• Enhanced type safety with strict types
• Improved dependency injection
• Better test coverage
• Updated quality tooling (PHPStan, Rector, Fractor)
• DDEV-based development workflow

Deprecations:

None in 3.0.x series.

Removed Features:

• TYPO3 12 and earlier support
• PHP 8.1 and earlier support

2.0.x Series 

Focus: TYPO3 12 LTS support

Key Features:

• TYPO3 12 LTS compatibility
• PHP 8.1+ support
• Modern Extbase patterns
• Backend module improvements

1.0.x Series 

Focus: Initial release and TYPO3 10-11 support

Key Features:

• Translation database management
• Import/Export functionality
• Backend module
• ViewHelper integration

From 2.x to 3.x 

Prerequisites:

• PHP 8.2 or higher installed
• TYPO3 13.4 or higher

Steps:

1. Backup your database and translations

2. Update composer.json:

   composer require netresearch/nr-textdb:^3.0

   Copied!

3. Update database schema:

   vendor/bin/typo3 database:updateschema

   Copied!

4. Clear all caches:

   vendor/bin/typo3 cache:flush

   Copied!
5. Test functionality thoroughly

Breaking Changes:

• PHP 8.2 minimum (check your PHP version)
• TYPO3 13.4 minimum (upgrade TYPO3 first if needed)
• Some internal APIs may have changed (check custom code)

From 1.x to 3.x 

Not Directly Supported

Upgrade path: 1. Upgrade to 2.x first 2. Test thoroughly 3. Then upgrade to 3.x

Version 3.0.1 

• No security issues

Version 3.0.0 

• Updated dependencies to address known vulnerabilities
• Enhanced input validation
• Improved file upload security

3.0.x Series 

BC Breaks:

• PHP 8.2 minimum
• TYPO3 13.4 minimum

API Stability:

Public APIs (ViewHelpers, Services) maintain backwards compatibility within the 3.x series.

Database Schema:

Database schema is compatible between 2.x and 3.x (with updates).