PHPackages                             netresearch/nr-textdb - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. netresearch/nr-textdb

ActiveTypo3-cms-extension[Database & ORM](/categories/database)

netresearch/nr-textdb
=====================

Auto-creating TYPO3 translation database - use ViewHelpers, editors translate in backend, instant updates - by Netresearch

v3.0.3(5mo ago)1738↓50%[6 issues](https://github.com/netresearch/t3x-nr-textdb/issues)[2 PRs](https://github.com/netresearch/t3x-nr-textdb/pulls)GPL-3.0-or-laterPHPPHP ^8.2CI passing

Since Sep 23Pushed 1mo ago4 watchersCompare

[ Source](https://github.com/netresearch/t3x-nr-textdb)[ Packagist](https://packagist.org/packages/netresearch/nr-textdb)[ RSS](/packages/netresearch-nr-textdb/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (15)Versions (54)Used By (0)

Netresearch TextDB
==================

[](#netresearch-textdb)

> **Manage TYPO3 translations directly in the backend – no more digging through language files**

[![Latest version](https://camo.githubusercontent.com/1fcdf6fce23bbdc8bb1a182fbffc64098b7737d2260b8ae450cb96926e19988f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6e657472657365617263682f7433782d6e722d7465787464623f736f72743d73656d766572)](https://github.com/netresearch/t3x-nr-textdb/releases/latest)[![TYPO3 13](https://camo.githubusercontent.com/ff624ed071afbc7085dcd4f99f2358379f8284ba14ae6891eab075f69c55929f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5459504f332d31332e342d6f72616e67652e737667)](https://get.typo3.org/version/13)[![PHP 8.2+](https://camo.githubusercontent.com/0f16581d1180dbfd4c0e13166ec1267d4ad2f2fab8281ea6d6b284cf5c65d921/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c75652e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/206beb4aeafb6c27c2336a3966fd0c122c5892d53ec238a8cdc9eaf3a3b72681/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6e657472657365617263682f7433782d6e722d746578746462)](https://github.com/netresearch/t3x-nr-textdb/blob/main/LICENSE)[![CI](https://github.com/netresearch/t3x-nr-textdb/actions/workflows/ci.yml/badge.svg)](https://github.com/netresearch/t3x-nr-textdb/actions/workflows/ci.yml)

---

What is TextDB?
---------------

[](#what-is-textdb)

TextDB is a powerful TYPO3 extension that transforms how you manage translations. Instead of editing language files scattered across your project, **manage all translations through a convenient backend module** with filtering, search, and bulk operations.

Perfect for:

- 🌍 **Multi-language websites** with frequent translation updates
- 👥 **Clients and editors** who need to update translations without touching code
- 🔄 **Translation workflows** requiring import/export capabilities
- 🚀 **Agencies** managing multiple TYPO3 projects with consistent translation processes

---

🎯 What TextDB Is (and Isn't)
----------------------------

[](#-what-textdb-is-and-isnt)

### ✅ TextDB is designed for: Frontend System Strings

[](#-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:

[](#-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

[](#-translation-scope)

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

```

---

📚 Real-World Use Cases
----------------------

[](#-real-world-use-cases)

### Use Case 1: Multi-Language E-Commerce Checkout

[](#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

[](#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

[](#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

[](#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.

---

🔄 Before & After: The TextDB Transformation
-----------------------------------------------

[](#-before--after-the-textdb-transformation)

### Traditional File-Based Approach (Without TextDB)

[](#traditional-file-based-approach-without-textdb)

```
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
├── typo3conf/ext/another_extension/
│   └── Resources/Private/Language/
│       └── ... more scattered files

```

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

[](#database-backed-approach-with-textdb)

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

[](#migration-path-zero-disruption)

**Phase 1: Prepare (5 minutes)**

```

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

**Phase 2: Auto-Import (Automatic)**

```

```

**Phase 3: Optimize (Gradual)**

```

```

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

---

✨ Features
----------

[](#-features)

### Backend Translation Management

[](#backend-translation-management)

- **User-friendly backend module** for managing all translations
- **Advanced filtering** by component, type, and placeholder
- **Multi-language support** with TYPO3's site configuration
- **Inline editing** of translations directly in the list view

### Import & Export

[](#import--export)

- **XLF file import/export** for easy translation workflows
- **Bulk operations** for updating multiple translations at once
- **Overwrite protection** with optional merge strategies
- **Multi-language export** for all configured site languages

### Migration Tools

[](#migration-tools)

- **ViewHelper for migration** from LLL files to database storage
- **Automatic translation detection** and import during migration
- **Backward-compatible** migration path preserving existing translations

### Developer Features

[](#developer-features)

- **Extbase ViewHelpers** (`textdb:textdb`, `textdb:translate`)
- **Console commands** for automated import workflows
- **Structured data model** (Environment → Component → Type → Placeholder)
- **TYPO3 v13 compatibility** with modern dependency injection

---

🌟 What Makes TextDB Unique
--------------------------

[](#-what-makes-textdb-unique)

### Competitive Comparison

[](#competitive-comparison)

FeatureTextDBl10nmgrSnowbabeltranslatelabelsTYPO3 Core**Frontend System Strings**✅ Primary Focus❌ No❌ No⚠️ Partial❌ Backend Only**Database-Backed Storage**✅ Yes✅ Yes✅ Yes✅ Yes❌ File-Based**Zero-Friction Migration**✅ Auto-Import❌ Manual❌ Manual❌ ManualN/A**Backend Module**✅ Advanced Filtering✅ Workflow-Heavy✅ Simple✅ Basic❌ No**XLF Import/Export**✅ Multi-Language ZIP✅ Complex Workflow⚠️ Limited❌ No✅ Single Files**Hierarchical Organization**✅ 4-Level Structure❌ Flat❌ Flat❌ Flat❌ File Structure**Live Translation Updates**✅ Instant⚠️ Via Workflow✅ Instant✅ Instant❌ Requires Deployment**Non-Developer Editing**✅ Backend Module⚠️ Complex✅ Simple✅ Basic❌ File Access Needed**Code Quality**✅ PHPStan 10⚠️ Lower⚠️ Lower⚠️ Lower✅ High**TYPO3 v13 Ready**✅ Yes⚠️ Legacy Support❌ Outdated❌ Unmaintained✅ Yes### Key Differentiators

[](#key-differentiators)

#### 🎯 1. Zero-Friction Migration

[](#-1-zero-friction-migration)

**The TextDB Advantage**: Drop-in replacement for `f:translate` ViewHelper with automatic LLL import on first render.

```

```

**Competitors**: Require manual migration, complex import processes, or complete rewrites.

---

#### 🏗️ 2. Hierarchical Organization

[](#️-2-hierarchical-organization)

**The TextDB Advantage**: 4-level structure (Environment → Component → Type → Placeholder) prevents chaos at scale.

**Example**: 500+ translations organized logically instead of 500 flat key-value pairs.

**Competitors**: Flat key-value structure becomes unmanageable beyond 100 translations.

---

#### ⚡ 3. Non-Developer Empowerment

[](#-3-non-developer-empowerment)

**The TextDB Advantage**: Product managers, translators, and editors update translations without:

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

**Competitors**: Either require developer involvement (TYPO3 Core) or offer basic editing without advanced features (Snowbabel).

---

#### 🔒 4. Production-Grade Quality

[](#-4-production-grade-quality)

**The TextDB Advantage**:

- 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

**Competitors**: Lower code quality standards, outdated codebases, limited testing.

---

#### 🚀 5. Developer Experience

[](#-5-developer-experience)

**The TextDB Advantage**:

- **Fast Apply-compatible**: Token-optimized for AI-assisted development
- **Modern Architecture**: Dependency injection, final classes, strict types
- **CLI Automation**: Console commands for import workflows
- **API-ready**: Clean service layer for programmatic access

**Competitors**: Legacy architectures, limited CLI support, manual workflows.

---

📋 Requirements
--------------

[](#-requirements)

- **TYPO3**: 13.4.0 - 13.99.99
- **PHP**: 8.2, 8.3, or 8.4
- **PHP Extensions**: zip, simplexml, libxml
- **Composer**: For installation and dependency management

---

🚀 Installation
--------------

[](#-installation)

Install via Composer:

```
composer require netresearch/nr-textdb
```

Activate the extension in the TYPO3 Extension Manager or via CLI:

```
vendor/bin/typo3 extension:activate nr_textdb
```

---

⚙️ Configuration
----------------

[](#️-configuration)

### Extension Configuration

[](#extension-configuration)

Configure the extension in the TYPO3 backend:

1. Navigate to **Admin Tools → Settings → Extension Configuration**
2. Select **nr\_textdb**
3. Set the **Storage PID** where translations will be stored
4. Optionally disable **"Create if missing"** feature

### Storage Setup

[](#storage-setup)

Create a dedicated storage folder for your translations:

1. Create a new page/folder in the TYPO3 page tree
2. Note the page ID
3. Set this ID in the extension configuration as the **Storage PID**
4. *(Optional)* Create language overlays for the folder to enable the language switcher in TCA

---

📖 Usage
-------

[](#-usage)

### Backend Module

[](#backend-module)

Access the TextDB module under **Netresearch → TextDB** in the TYPO3 backend.

**Key Features:**

- **List View**: Browse and filter all translations
- **Inline Editing**: Click to edit translation values directly
- **Filtering**: Filter by component, type, or search in placeholders/values
- **Pagination**: Navigate through large translation sets

### ViewHelper Usage

[](#viewhelper-usage)

Use TextDB translations in your Fluid templates:

```

```

**ViewHelper Parameters:**

- `component`: Logical grouping (e.g., "checkout", "contact-form")
- `type`: Translation type (e.g., "label", "message", "error")
- `placeholder`: Unique identifier for the translation

---

📥 Import & Export
---------------------

[](#-import--export)

### Importing Translations

[](#importing-translations)

1. Prepare an XLF file with the required structure (see below)
2. Open the TextDB backend module
3. Click **Import**
4. Select your XLF file
5. Check **"Overwrite existing"** if you want to update existing translations
6. Click **Import**

**XLF File Structure for English (source language):**

```

            Your Name
            your@email.com

                Translation Value

```

**XLF File Structure for Other Languages:**

```

            Your Name
            your@email.com

                Übersetzungswert

```

**File Naming Convention:**

- English (default): `textdb_[name].xlf`
- Other languages: `[iso-code].textdb_[name].xlf` (e.g., `de.textdb_labels.xlf`)

#### Security Considerations

[](#security-considerations)

The XLF import functionality implements protection against XML External Entity (XXE) attacks:

- **XXE Protection**: Network access during XML parsing is blocked using the `LIBXML_NONET` flag, preventing external entity resolution and SSRF attacks
- **PHP 8.0+ Compatible**: External entity loading is disabled by default in PHP 8.0+, with `LIBXML_NONET` providing defense-in-depth security
- **Permission Requirements**: Only backend users with appropriate permissions can import XLF files
- **Best Practices**:
    - Review XLF files from untrusted sources before importing
    - Monitor import operations in production environments
    - Regularly update to the latest version to receive security updates

For more information about XXE vulnerabilities, see the [OWASP XXE documentation](https://owasp.org/www-community/vulnerabilities/XML_External_Entity_(XXE)_Processing).

### Exporting Translations

[](#exporting-translations)

1. Open the TextDB backend module
2. Apply filters (component, type) if needed
3. Click **"Export with current filter"**
4. A ZIP archive will be downloaded with XLF files for all languages

**Note**: Export includes all filtered translations, ignoring pagination.

---

🔄 Migration from LLL Files
--------------------------

[](#-migration-from-lll-files)

Migrate existing `f:translate` ViewHelpers to TextDB:

### Step 1: Include TextDB ViewHelper

[](#step-1-include-textdb-viewhelper)

Add to your template:

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

### Step 2: Set Component in Controller

[](#step-2-set-component-in-controller)

```
use Netresearch\NrTextdb\ViewHelpers\TranslateViewHelper;

// In your controller action
TranslateViewHelper::$component = 'my-component';
```

### Step 3: Replace ViewHelpers Temporarily

[](#step-3-replace-viewhelpers-temporarily)

Replace `f:translate` with `textdb:translate`:

```

```

### Step 4: Render Templates

[](#step-4-render-templates)

Access your frontend to trigger automatic import of translations into TextDB.

### Step 5: Final Replacement

[](#step-5-final-replacement)

Replace all `f:translate` calls with `textdb:textdb`:

**For tag syntax:**

```
Search: