Developer Manual 

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

Type

string

Required

true

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

type

Type

string

Required

true

Default

P

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

placeholder

Type

string

Required

true

Unique translation key within the component and type context.

environment

Type

string

Required

false

Default

default

Environment name for contextual translations.

Output:

Returns the translated text for the current page language. When that language has no usable entry, the ViewHelper falls back as described in Lookup Order and Language Fallback.

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

Lookup Order and Language Fallback 

Both ViewHelpers look for a value in this order and render the first one they find:

1. The TextDB entry in the current language. A hidden entry, an entry with an empty value, or one that was auto-created and never edited, does not count. A value that equals its key (Login → Login) does count.
2. textdb:translate only: the label from the language file (XLIFF). This is the label in the current language or, when the file has no translation for the key, the file's source label. Step 3 therefore runs for textdb:translate only when the key is in no language file, or its label is empty.
3. The TextDB entries in the languages of the site language's fallback chain (fallbackLanguageIds in the site configuration), in their order, then the entry in the default language (0). The same rules as in step 1 apply to each entry.
4. The key itself.

TYPO3 passes the fallbackLanguageIds on for every fallbackType, so step 3 follows them for strict, fallback and free alike. A site language without fallback languages still falls back to the default language in step 3.

When createIfMissing is enabled, step 1 creates the missing entry in the current language, as before. Steps 3 and 4 never create translation records.

A hidden entry renders like a missing one: in step 1 the lookup goes on with step 2, and in step 3 the hidden entry is skipped. The lookup still finds the hidden entry, so createIfMissing does not create a second entry for its key. The backend module lists, edits, exports and imports hidden entries as before. Deleted entries are never found.

For example, a German page (language 1) whose site language falls back to 0 renders the English TextDB entry when no German entry exists. With textdb:translate, a label in the language file wins over that English entry, whether it is the German label or the file's source label.

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!

translate() looks up the current language only. It returns the key both when there is no usable entry and when the value equals the key; use findTranslation() to tell the two apart.

findTranslation()                  

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

Copied!

Same lookup as translate(), including the auto-creation with createIfMissing, but returns null when the current language has no usable entry: none, a hidden one, an empty value, or an auto-created one. The ViewHelpers use it for step 1 of Lookup Order and Language Fallback.

returns

The value, or null if the current language has no usable entry

translateFromFallbackLanguages()                                 

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

Copied!

Returns the value of the first usable entry along the fallback chain of the current language, then in the default language, as in step 3 of Lookup Order and Language Fallback. The current language itself is not searched. The method never creates translation records.

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 value, or null if no fallback language has one

Example:

$value = $this->translationService->findTranslation('welcome.message', 'label', 'website', 'default')
    ?? $this->translationService->translateFromFallbackLanguages('welcome.message', 'label', 'website', 'default')
    ?? 'welcome.message';

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:

The counts, the error messages and the keys of skipped units collect on an ImportResult that the caller creates and passes in. One result can go through several calls; read the totals at the end.

public function importFile(
    string $file,
    bool $forceUpdate,
    ImportResult $result,
): void

use Netresearch\NrTextdb\Service\ImportResult;

$result = new ImportResult();

$this->importService->importFile('/path/to/de.textdb_website.xlf', true, $result);

echo sprintf('Imported: %d, Updated: %d', $result->getImported(), $result->getUpdated());

foreach ($result->getErrors() as $error) {
    echo $error, PHP_EOL;
}

public function loadFile(string $file, string $locale): LoadedXliffFile

public function importEntries(
    array $entries,
    int $languageUid,
    bool $forceUpdate,
    ImportResult $result,
    array $unapprovedKeys = [],
    array $partiallyApprovedKeys = [],
): void

public function importEntry(
    int $languageUid,
    ?string $componentName,
    ?string $typeName,
    string $placeholder,
    string $value,
    bool $forceUpdate,
    ImportResult $result,
): bool

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\ImportResult;
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) {
            $result = new ImportResult();

            try {
                $this->importService->importFile($file, false, $result);
            } catch (\Throwable $exception) {
                $output->writeln('<error>' . $exception->getMessage() . '</error>');
            }

            $output->writeln(sprintf(
                'Imported: %d, Updated: %d from %s',
                $result->getImported(),
                $result->getUpdated(),
                $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?