Configuration

Extension Configuration

Configure the extension via Admin Tools > Settings > Extension Configuration > nr_textdb

Available Settings

textDbPid

type: string (integer)
Default: (empty)
Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb']['textDbPid']

The Page ID (PID) where TextDB translations should be stored.

This should point to a dedicated storage folder in your page tree.

Important

This setting is required for the extension to function properly.

Example

Configure in Admin Tools > Settings > Extension Configuration > nr_textdb:

textDbPid = 123

createIfMissing

type: boolean
Default: true
Path: $GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb']['createIfMissing']

Automatically create translation records if they don't exist when requested via ViewHelpers.

When enabled, missing translations will be auto-created with placeholder text. When disabled, only existing translations will be displayed.

The setting governs lookups only. Opening the backend module does not switch it on: with the setting disabled, a lookup made during a backend request creates no component, type, environment or translation record. The backend module's own writes are unaffected, because they do not depend on the setting. Saving a translation for a language that has none yet and importing an XLIFF file create their records with the setting disabled as well.

Tip

Enable this during development to quickly identify missing translations. Disable in production if you want strict translation management.

Example

config/system/additional.php

// Development: auto-create missing translations
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb']['createIfMissing'] = true;

// Production: strict mode
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['nr_textdb']['createIfMissing'] = false;

TypoScript Configuration

The extension includes default TypoScript configuration that is automatically loaded.

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

Backend Module Configuration

Access Control

The TextDB backend module requires appropriate permissions:

Module Access:

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

Record Permissions:

The module stores records through Extbase, not DataHandler, so it checks the group's record permissions itself on every action. Admins pass the table, page and field checks.

Action	Table permissions	Page permission
List, view translations, export	Read (`tables_select`) on all four TextDB tables	"Show page" on the storage page (`textDbPid`) and, for a single record, on the record's page; the pages must be in the user's mounts. The list and the export show a non-admin only the records stored on the storage page
Save translations	Read on all four tables and modify (`tables_modify`) on `tx_nrtextdb_domain_model_translation`	"Edit content" on the storage page and on the page of every changed record
Import	Modify on all four tables, because an import creates missing components, types and environments	"Edit content" on the storage page

Saving and importing also need:

the language: a translation in a language the group's language list does not allow is not saved, and an import file for such a language is not imported;
the excluded fields (Allowed excludefields): saving needs the translation's value field; adding a translation in a language that has none yet also needs sys_language_uid, environment, component, type and placeholder; an import needs all of these plus the name field of components, types and environments;
the live workspace: the TextDB tables are not workspace-aware, so in a draft workspace the module makes no changes unless the workspace allows live editing.

The four tables are:

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',
        ],
    ],
],

Service Configuration

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

Database Configuration

Table Configuration (TCA)

The extension defines TCA for four tables:

Translation Records

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

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

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

Icon Configuration

Icons are registered in Configuration/Icons.php:

return [
    'extension-netresearch-module' => [
        'provider' => SvgIconProvider::class,
        'source' => 'EXT:nr_textdb/Resources/Public/Icons/ModuleGroup.svg',
    ],
    'extension-netresearch-textdb' => [
        'provider' => SvgIconProvider::class,
        'source' => 'EXT:nr_textdb/Resources/Public/Icons/Module.svg',
    ],
    'nr-textdb-record-component' => [
        'provider' => SvgSpriteIconProvider::class,
        'sprite' => 'EXT:nr_textdb/Resources/Public/Icons/tx_nrtextdb_domain_model_component.svg#tx_nrtextdb_domain_model_component',
    ],
    // nr-textdb-record-environment, -translation and -type follow the same pattern
];

The glyphs use currentColor, so they follow the backend colour scheme. The group icon is rendered inline in the module menu. The record icons are sprite icons, referenced from the TCA through ctrl.typeicon_classes, so TYPO3 renders them as <svg><use> instead of <img>. Extension.svg stays the extension logo shown in the Extension Manager.

Language Files

The extension uses XLIFF files for localization:

Resources/Private/Language/
├── locallang.xlf                  # General labels
├── locallang_db.xlf               # Database field labels
├── locallang_mod.xlf              # Main module labels
├── locallang_mod_textdb.xlf       # TextDB module labels
├── de.locallang.xlf               # German translations
├── de.locallang_db.xlf
├── de.locallang_mod.xlf
└── de.locallang_mod_textdb.xlf

Adding Custom Translations

To add support for additional languages:

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

Advanced Configuration

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/',
    ],
];

Environment-Specific Configuration

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