---
title: "User Manual"
manual: "TextDB"
version: "4.1"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-textdb:user-manual@4.1"
source: "User/Index.rst"
rendered: "2026-10-31T14:42:22+00:00"
---

# User Manual {#user-manual}

## Introduction for Editors {#user-introduction}

The TextDB extension provides a user-friendly interface for managing translations
directly in the TYPO3 backend. As an editor, you can:

-   View and edit existing translations
-   Filter translations by component, type, and environment
-   Import and export translation files
-   Search for specific translations
-   Manage multilingual content without technical knowledge

## Accessing the TextDB Module {#accessing-module}

1.  Log in to the TYPO3 backend
1.  In the left menu, click on **Netresearch**
1.  Select **Netresearch TextDB** from the submenu

The TextDB module is located under the **Netresearch** section in the backend menu.

## Viewing Translations {#viewing-translations}

### List View {#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 {#pagination}

Large translation sets are automatically paginated:

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

## Filtering Translations {#filtering-translations}

Use the filter options to narrow down your results:

### Component Filter {#component-filter}

Select a specific component to show only its translations:

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

### Type Filter {#type-filter}

Filter by translation type:

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

### Search {#search}

Search for specific translations:

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

> [!TIP]
> Combine filters for precise results (e.g., Component + Type + Search)

## Editing Translations {#editing-translations}

### Edit Single Translation {#edit-single-translation}

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

### Multi-Language Editing {#multi-language-editing}

To edit translations in different languages:

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

> [!WARNING]
> **Attention**
>
> Ensure you're editing the correct language before making changes!

### Hiding a Translation {#hiding-a-translation}

A translation record can be hidden on the **Access** tab of its record form
in the **List** module. The frontend then renders it as if it did not exist:
it shows the label from the language file (`textdb:translate` only), the
translation of a fallback language, or the key. The record stays in the TextDB module and is still
exported. Unhide it to show its value again.

## Importing Translations {#importing-translations}

### Import from XLIFF File {#import-from-xliff-file}

1.  Click the **Import** button in the toolbar
1.  Select the XLIFF file to import
1.  Choose import options:

    -   **Overwrite Existing**: Check to replace existing translations
    -   Leave unchecked to only import new translations
1.  Click **Import**
1.  Review the import summary

### Units the Import Skips {#import-skipped-units}

The import names the units it leaves out or shortens after the import, in
one warning per kind. Each warning gives the number of units and the keys of
the first ten.

**Not approved.** In a translation file (XLIFF 1.2 with `target-language`,
XLIFF 2.0 with `trgLang`), TYPO3 reads only approved units while
`$GLOBALS['TYPO3_CONF_VARS']['LANG']['requireApprovedLocalizations']` is
enabled, which is the TYPO3 default. A unit is not approved when it is
marked `approved="no"` (XLIFF 1.2) or when its segment has
`state="initial"` or `state="translated"` (XLIFF 2.0). The warning names
the setting. To import such units, approve them in the file, or ask the
administrator to disable the setting. The setting applies to every XLIFF
file TYPO3 reads, not only to the TextDB import.

**Plural forms not approved.** The same setting applies to each form of a
plural unit (a `restype="x-gettext-plurals"` group in XLIFF 1.2, a unit
with several segments in XLIFF 2.0). When only some of its first two forms
are approved, the unit is imported with the approved forms only, and the
warning names it. When its record already exists and **Overwrite Existing** is
not checked, the record is kept and the unit is not named. When no form is approved, the unit counts as not approved.
When the approved forms have no text, the unit is reported as having no text.

**No text.** A unit whose text is empty or only whitespace, for example an
untranslated unit without `<target>` in an XLIFF 1.2 translation file.
Importing it would overwrite the stored value with nothing.

Three cases are not reported, because TYPO3 drops the text while reading
the file and the import never sees it:

-   A unit of an XLIFF 2.0 translation file without `<target>`. It is not
    imported.
-   A segment without `<target>` in a plural unit of an XLIFF 2.0
    translation file. The unit is imported without that form.
-   The third and every later form of a plural unit, as languages such as
    Russian or Polish have. TYPO3 keeps the first two forms only, whether the
    later ones are approved or not, so these forms are never imported, and a
    plural unit whose only unapproved form is the third or a later one is not
    reported.

A unit of a default-language file (no `target-language` or `trgLang`) is
never skipped for approval.

### Expected File Format {#expected-file-format}

English Source File (en):

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

> [!IMPORTANT]
> File naming convention:
>
> -   English: `textdb_[name].xlf`
> -   Other languages: `[lang].textdb_[name].xlf` (e.g., `de.textdb_website.xlf`)

## Exporting Translations {#exporting-translations}

### Export Filtered Translations {#export-filtered-translations}

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

### Use Cases for Export {#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

## Translation Workflow {#translation-workflow}

### Typical Workflow {#typical-workflow}

1.  **Developer** creates placeholder translations
1.  **Editor** reviews and refines translations
1.  **Translator** (if needed):

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

### Best Practices {#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

## Troubleshooting {#troubleshooting-user}

### Translation Not Showing {#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 {#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**: A file with tens of thousands of entries can take longer
    than the time limit of the backend. Split it into smaller files, or ask
    the administrator to import it with the CLI command
-   **Database Error**: The file was not imported at all, not even in part.
    The message names the cause, a component name longer than 255 characters
    for example. Correct the file and import it again

### Cannot Edit Translation {#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

## Keyboard Shortcuts {#keyboard-shortcuts}

The TextDB module supports standard TYPO3 keyboard shortcuts:

-   **Ctrl+S**: Save current record (when editing)
-   **Ctrl+Shift+S**: Save and close
-   **Escape**: Close edit form without saving

## Tips & Tricks {#tips-tricks}

### Quick Search {#quick-search}

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

### Bulk Operations {#bulk-operations}

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

### Favorites {#favorites}

Bookmark frequently used filter combinations in your browser.

### Translation Preview {#translation-preview}

Keep a frontend tab open to immediately verify translation changes.