Known Problems 

TYPO3 Version Support 

• Minimum TYPO3: 14.3.0
• Earlier versions: Not supported by this version. Use version 3.x for TYPO3 13.4 and version 2.x for TYPO3 12.4.

PHP Version Requirements 

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

Import Performance 

Issue: A large XLIFF file can take longer than the time limits of a backend request.

An import writes every entry of a file in one database transaction, the translations in chunks of 1,000 entries without Extbase. A file of 10 MB with 48,500 units imported in these times through the import service, with a memory limit of 256 MB (median of three runs):

• SQLite: 10 seconds; a second import of the same file with Override existing 1 second
• MariaDB 10.11: 44 seconds; the second import 1 second
• PostgreSQL 16: 31 seconds; the second import 1 second

An import that changes all 48,500 values took 5 seconds on SQLite, 39 seconds on MariaDB and 26 seconds on PostgreSQL. No import through the service needed more than 176 MB of memory.

The same file uploaded in the backend module took 44 seconds on MariaDB, of which 25 seconds were CPU time, and finished with PHP's default max_execution_time of 30 seconds on the measured host, about 5 seconds short of the limit, using at most 188 MB of memory; a second upload with Override existing took 1 second. On Linux, PHP counts only the time the script itself runs against that limit, not the time it waits for the database, see the note in the PHP manual on set_time_limit(). A web server or proxy timeout counts the whole 44 seconds.

If an import fails, the file imports nothing, on every supported database, and the backend module and the CLI command show the error.

Workaround:

• Import large files with the CLI command nr_textdb:import, which has no time limit
• Split large files into smaller files for the backend module. A file uploaded there must also fit PHP's upload_max_filesize and post_max_size, which default to 2 MB and 8 MB.
• Set the request timeout of the web server and of a proxy in front of it above the wall time above, for example to the 240 seconds TYPO3 recommends for max_execution_time.

Status: Improved. On the measured host, the 10 MB file imports in a backend request within PHP's default time limit, with about 5 seconds to spare; the time limits of the web server remain.

GitHub Issue: #30

Language Fallback 

Issue: When the current language had no entry, the ViewHelpers rendered the bare key instead of a value from another language.

Status: Resolved. The ViewHelpers now follow the fallback chain of the site language and then the default language. See Lookup Order and Language Fallback for the lookup order.

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 

The functional test suite runs in CI against these database servers:

• SQLite
• MariaDB 10.11
• MySQL 8.0
• PostgreSQL 16

Other versions of these servers are not tested.

Backend Module 

The TextDB backend module runs in the TYPO3 backend and has no browser requirements of its own. Its tests do not run in a browser. TYPO3 14.3 lists the latest versions of Chrome, Edge, Firefox and Safari as supported browsers, see the system requirements of TYPO3 14.

Problem: Module Not Visible 

Symptoms:

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

Solution:

1. Check that the extension is active and its module registered, and flush the caches, which hold the module registration:

   vendor/bin/typo3 extension:list | grep nr_textdb
   vendor/bin/typo3 debug:backend:modules | grep netresearch_textdb
   vendor/bin/typo3 cache:flush

   Copied!
2. For an editor who is no administrator, check that the backend user or one of the user's groups lists the module Netresearch > TextDb in Allowed modules on the tab Module Permissions.

Problem: Translations Not Updating 

Symptoms:

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

Cause:

The ViewHelpers render the value into the page, and TYPO3 keeps the rendered page in the page cache. With TYPO3's default configuration, saving an entry in the module does not clear the cache of the pages that show the value.

Solution:

1. Flush the page cache, in the backend with Flush frontend caches in the cache menu of the toolbar, or on the command line:

   vendor/bin/typo3 cache:flush --group pages

   Copied!
2. If the value is still old, check that the entry is stored in the folder that textDbPid in the extension configuration names. The ViewHelpers read entries from that folder only.

Problem: Import Fails Silently 

Symptoms:

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

Solution:

1. Check the size of the file. A file larger than PHP's upload_max_filesize or post_max_size does not reach the module, which then shows the empty import form again without a message.

2. Verify the XLIFF format. The module imports the <trans-unit> elements of <file><body>, and each id names component, type and placeholder. A file exported by the module has this structure:

   <?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 the language prefix of the file name. de.textdb_import.xlf imports into the site language whose language code is de, and a file without prefix into the language with the code en. The languages come from the site of the storage folder. A prefix that no language of this site has imports nothing and shows no message.
4. Select Override existing to change entries that exist already. Without it the import leaves them unchanged and does not count them. Entries the extension created automatically are overwritten in both cases.
5. Read the warnings about skipped units. The import names the units it leaves out because they are not approved or have no text, and the plural units it imports without their forms that are not approved, see Units the Import Skips. Three cases it does not report, because TYPO3 drops the text while reading the file: a unit of an XLIFF 2.0 translation file without <target>, which is not imported; a segment without <target> in an XLIFF 2.0 plural unit, which is imported without that form; and the third and later forms of any plural unit, which TYPO3 never keeps, so a plural unit whose only unapproved form is the third or a later one is not reported. Check such a file for units and segments without <target> and for plural units with more than two forms.

Problem: Line Breaks Lost After Re-Import 

Symptoms:

• After importing an exported file, values that had line breaks or repeated spaces show them as single spaces

Cause:

The import reads files with TYPO3's XLIFF loader, which collapses whitespace in a unit unless the unit declares xml:space="preserve". Files exported by version 4.0.2 and earlier do not declare it.

Solution:

Export the translations again and import the new file instead of the old one. This helps only while the stored values still have their line breaks. A value that an import has already flattened is stored without them, so a new export carries the flattened value as well. Restore such a value from the original XLIFF file or a database backup, or edit it in the backend module.

Problem: Export Exceeds the Time Limit 

Symptoms:

• The export of a large data set ends with a timeout

Cause:

The export reads the entries in batches of 1,000. Measured on SQLite with entries in the default language and one translation of each:

• 10,000 entries: 9 seconds, 10 MB of memory beyond the request
• 48,500 entries: 44 seconds, 28.5 MB of memory beyond the request

Version 4.0.2 and earlier read all entries at once, so their memory use grows with the data set.

Solution:

• Raise max_execution_time for backend requests. TYPO3 recommends 240 seconds.
• Narrow the export with the filters of the module, for example to one component and type.

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