Localization Manager (l10nmgr)

Localization Manager (l10nmgr) 

Classification

localization

Version

12.2

Language

en

Keywords

localization translation l18n

Copyright

2006-2021, Christian Zielinski, zielinski@loctimize.com

Maintainer

CodersCare

Author

Christian Zielinski

License

This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml

Rendered

Fri, 03 Oct 2025 12:09:49 +0000

The content of this document is related to TYPO3, a GNU/GPL CMS/Framework available from www.typo3.org.

Table of Contents

What does it do? 

The Localization Manager (l10nmgr) is a localization management extension for TYPO3 supporting a variety of online and offline translation workflows.

Online translation 

Online translation in the TYPO3 backend can be done in a two column view with additional information on changes in the source text.

Offline translation 

For offline translation workflows the l10nmgr allows for export of translatable content into XML and MS Excel format. The exported XML files have a localization-friendly format and can be translated with any state of the art translation tool such as across, DéjàVu, MemoQ, SDL TRADOS TagEditor and SDL PASSOLO. Configuration files for major translation tools are provided and can be downloaded in the backend. MS Excel files can be translated in OpenOffice Calc or Microsoft Excel. After translation the target files can be reimported into TYPO3. All translation data is stored automatically in the right place – no manual copying anymore.

Automation 

Exports for different parts of the website and for multiple target languages at the same time can be automated and exported files can be uploaded automatically to the FTP server of a language service provider or send by email. Translated XML files (XML or ZIP) can be automatically imported into TYPO3 by an import service.

Localization of TYPO3 websites 

According to the adopted localization concept, new localizations of a web page and their respective content elements are mainly realized either with language overlays or with a one-tree-per-language approach, where the whole source page tree is copied (sometimes onto a different TYPO3 installation).

Although TYPO3 comes with all necessary localization features, localization of larger TYPO3 web sites is very often a tedious and time-consuming task. Translation of pages and content elements is often done inside TYPO3 by manually localizing (translating) a web page and copying the default content elements, which are then overwritten with the translation. This requires translators to have access to and knowledge about TYPO3 (how to access TYPO3, how to use the RTE, how to localize or translate a page, etc.). While translating within TYPO3, translators do not have support from professional translation tools – such as translation memories, terminology databases or spell-checkers – which usually guarantee consistency of translations and terminology, as well as the efficiency of the translation process. This makes translators and translation service providers (as well as TYPO3 administrators) somewhat unhappy...

The other possible route to localizing a TYPO3 website is to dump the database tables containing the localizable information (pages, tt_content,...) e. g. into *.csv format, then to translate the content and import it into another TYPO3 installation. This approach enables the use of professional translation tools but requires the database tables to be translated as a whole, as no subset can be exported. Furthermore, one has to cope with lowlevel problems such as choosing the right separator. Little programming or SQL knowledge is required. However, this approach works only for the one-tree-per-language approach.

Support and automation of the localization process 

Given this situation, the main idea behind developing Localization Manager was to realize a tool that supports and automates the localization process in order to make it more userfriendly. The user managing the website localization (e.g. administrator or project manager) should be able to export the localizable data so that it can be sent or assigned to translators. After translators have finished their work (using their CAT tools), translations can be sent back to the responsible person, who re-imports then the files into TYPO3. On import, all data in localized pages and content elements and the relations between them are automatically inserted into the database.

Translation workflow without l10nmgr 

Translators work directly in TYPO3. They do not have support from translation tools, translation memories and terminology databases or spell checkers. For each page to be translated the following steps have to be performed:

  1. Access the page to be translated,
  2. Translate the web page into $LANGUAGE
  3. Insert translations for all fields in the new translation form
  4. Copy default content elements
  5. Open each content element to overwrite the sourcetext with the translation.

To translate e.g. 50 web pages containing 300 content elements you would need at least 800 mouse clicks – not counting the typing of the translation.

|img-translation-workflow-without-l10nmgr|

Translation workflow with l10nmgr 

Translators do not have to access TYPO3. Translation is done in integrated translation tools with translation memories, terminology databases, spell checkers, etc. Translators can work offline and only need to translate the exported XML files.

|img-translation-workflow-with-l10nmgr|

Features 

In its current version Localization Manager comprises the following features:

General features 

  1. Support for all contents (pages, content elements) including contents from internationalized extensions (e.g. tt_news) and flexible content elements
  2. Workspace support: Allows for translation workflows in offline workspaces
  3. TemplaVoilà support

Export features 

  1. Fine grained export configurations (via Localization Manager Configuration record)

  2. Export of localizable content (pages and page content) into

    1. a localization-friendly XML format
    2. MS Excel XML (for translation in MS Excel or OpenOffice Calc)
  3. Selection of localizable page and content element types as well as localizable database table fields
  4. Check for already localized pages and content elements

  5. Options

    1. export only new/changed content
    2. skip export of hidden content elements
    3. single page export, recursive export
    4. exclude selected elements from export
    5. include selected elements from export
    6. check encoding (UTF-8)
    7. check XML for wellformedness
    8. select source languages other than the default language (important for relay translations)
  6. Predefined configuration files for across, DéjàVu, memoQ, SDL TRADOS TagEditor, SDL Trados Studio 2009, and SDL PASSOLO, which avoids time-consuming manual setup

  7. Automation of exports via command line scripts (CLI) with

    1. multiple Localization Manager configurations
    2. for multiple target languages
    3. upload of source language XML files to remote server via FTP
    4. sending source language XML files via email

Import features 

  1. Re-import of localized XML files
  2. Automatic insertion of localized pages and page content into TYPO3 database

  3. Options:

    1. Overwrite existing translations (pages and content elements)
    2. Generate preview links (e.g. if translations are imported in a workspace)
    3. Write back to default language, e.g. when copying a tree.

Workflow features 

  1. Localization overview (very basic)

XML exchange format 

The XML format used by the l10nmgr is a simple XML format that can be used with all state-of-the-art localisation and translation tools. The Localization Manager ships with the required settings files that specify translatable and non-translatable elements. Currently settings files are available for the following tools: across, DéjàVu, SDL Trados and SDL Passolo. Settings files for other tools can easily be set up. The file format for the export & import of translatable data of a TYPO3 website is a localization-friendly XML format. The default encoding of XML files is UTF-8. Context information One important feature of the XML format is that the translatable contents (<data> elements) are grouped according to the context of the page on which they occur (<pageGrp>). To get a preview of the source web page, the URL can be reassembled by combining the <baseURL> with the ID attribute of the <pageGrp> element and the ID of the source language (<sysLang>):

sysLang\>

Structure 

Element name Semantics
<TYPO3L10N> Root element
<head> Header with meta information
<t3_l10ncfg> ID of Localization Manager configuration used for the export.
<t3_sysLang> ID of target language (equal to IDs of website languages)
<t3_sourceLang> ISO-639-1 language code for source language
<t3_targetLang> ISO-639-1 language code for target language
<t3_baseURL> Base URL of TYPO3-Website to be translated
<t3_workspaceId> ID of workspace from which has been exported
<t3_count> Number of exported data sets
<t3_wordCount> Word count of source text
<t3_internal> Internal messages
<t3_skippedItem> Elements skipped during export
<t3_description> Error messages
<t3_key> Key of skipped element
<t3_formatVersion> Version number of XML format
<pageGrp> Grouping element that embraces all translatable elements of a page. The id- attribute indicates the page ID. The sourceUrl attribute indicates the url of the source language webpage.
<data> Translatable contents. Used attributes: table = database table from which contents has been exported elementUid = UID of localizable data set key = Trigger for localization command. Syntax: table:NEW/ t3_sysLang/elementUid:fieldname (Initial localization) table:elementUid:fieldname (Update localization, elementUid is ID of data set to be updated)
  <data> can further contain all kind HTML elements. Number and type of elements can vary for every TYPO3 installation.

Screenshots 

See section Users manual.

Installation 

Download the extension from the TYPO3 extension repository or from forge.typo3.org. Then install it with the extension manager. If you already use an older version of l10nmgr, make a backup of the extension directory. In case something fails, you'll have the possibility of re-establishing the original installation state from where you started the update.

Enabling hooks for processing of custom tags 

Extensions may add custom tags to RTE-enabled fields. First and foremost is the DAM, which adds tag <media>. Upon export to CAT XML, this tag must be interpreted (as when loaded into the RTE) otherwise it is exported with < and > transformed to HTML entities, and reimported as such, breaking all links to RTE files. Because there might be many different custom tags used in a TYPO3 installation we decided against including default implementations. If you want to use e. g. the hook to transform the DAM media tag you can add the following PHP code to your localconf:

$TYPO3_CONF_VARS['EXTCONF']['l10nmgr']['transformation']['txdam_media'] = 'EXT:dam/binding/mediatag/class.tx_dam_rtetransform_mediatag.php:&tx_dam_rtetransform_mediatag';
$TYPO3_CONF_VARS['EXTCONF']['l10nmgr']['transformation']['ts_links'] = 'EXT:dam/binding/mediatag/class.tx_dam_rtetransform_ahref.php:&tx_dam_rtetransform_ahref';
Copied!

Platforms and versions supported 

  1. TYPO3 CMS 6.2 (for TYPO3 CMS 4.x versions use l10nmgr 3.4.50)
  2. Linux/Unix Server, Windows
  3. Apache, MySQL,
  4. PHP5 (recommended 5.2 or higher)
- compiled with --enable-pcntl for automation via /services
  • compiled with --enable-zip for zip generation (v4)

Creating a Localization Manager configuration 

The Localization Manager first requires a Localization Manager configuration record in which you define the scope of translation or export/import of localizable contents. The Localization Manager configuration is a record that has to be created at the starting point in the page tree from which you want to start your translation or export/import. To create a Localization Manager configuration record, proceed as follows:

  1. Go to the backend and click on Web > List
  2. Select the first page in the page tree from where you want to start your translation
  3. In the right window click Create new record and then select Localization
  4. Fill in the fields as shown in the following screenshot
  5. Save the configuration

|img-manager-configuration|

Online translation 

To translate online in the TYPO3 backend do the following:

  1. Go to the backend and click on Web > Localization Manager.
  2. Select your previously created localization configuration from the table and click on the name of the configuration. This opens the Localization Manager and loads settings from the configuration.
  3. Select the target language for your export from the drop-down list.
  4. Select Online translation from the drop-down list and fill in the translations into the form.
  5. Upon completion click Save to store the translations to the database.

|img-online-tranlation-form|

Export 

The export function allows for exporting pages and their content into a) a localization-friendly XML format or b) the MS Excel XML format. In order to export pages and page content to be localized, proceed as follows:

  1. Go to the backend and click on Web > Localization Manager.
  2. Select your previously created localization configuration from the table and click on the name of the configuration. This opens the Localization Manager and loads settings from the configuration.
  3. Select the target language for your export from the drop-down list.
  4. Select XML Export/Import or MS Excel Export/Import from the drop-down list and click on the Export tab. For translation with professional translation tools choose XML. For translation with MS Excel or OpenOffice Calc choose Excel.

Note: Although Excel is a quite popular localization format it usually is tricky to translate when exported from TYPO3 as a lot of HTML or TYPO3 tags might be displayed as text making it hard to read and translate the text. So the recommendation is definitely to go for translation using the XML format.

|img-xml-export-settings|

  1. New/changed content only: Check this option if you only want to export new or changed content for translation. The comparison is always based on the default language version of an element.
  2. No hidden content: Check this option if you do not want to export hidden content elements (often content elements that are still not ready to be published).
  3. Check for already exported content: Check this option if you want to make sure that you don't export the same translation job twice.
  4. Do not check XML: Select this option if you don't want to use the inbuilt XML check. In that case Localization Manager includes content that is not XML well-formed as CDATA elements. Otherwise this contents is not exported and you will find error messages indicating the Ids of the skipped elements.
  5. Check encoding (UTF-8): Check this option if you want to make sure that the output XML file consistently used UTF-8 encoding.
  6. Force source language: Select a language from the drop-down list to choose a source language for translation other than the default language (relay translations)
  7. Click on Export to start the export.
  8. The data is now retrieved and packed into the desired file format.
  9. Save the export file.

|img-excel-export-settings|

Download configuration files 

Localization Manager comes with predefined configuration files for Across, DéjàVu, memoQ, SDL TRADOS TagEditor, SDL Trados Studio and SDL PASSOLO. Configuration files or settings files contain information about the localization format, e.g. which tags are internal or external, which tags or attributes are translatable or not, etc. With this information translation tools are able to extract only translatable information from the file and protect non-translatable information from being touched. Download the configuration files and send them to the translator or translation service provider together with the XML.

To download the configuration files, proceed as follows:

  1. Go to Web>Localization Manager in the backend.
  2. Select a localization configuration from the table and click on the name of the configuration. This opens the Localization Manager and loads settings from the configuration.
  3. Select the target language for your export from the drop-down list.
  4. Select XML Export/Import from the drop-down list and click on the Settings tab.
  5. Download the configuration file for your translation tool with a right-click on the desired configuration > Save target as

Import 

To import the translated XML or MS Excel files, proceed as follows:

  1. Go to Web>Localization Manager in the backend.
  2. Select your previously created localization configuration from the table and click on the name of the configuration. This opens the Localization Manager and loads settings from the configuration.
  3. Select the target language for your export from the drop-down list.
  4. Select XML Export/Import or MS Excel Export/Import from the drop-down list and click on the Import tab.

  5. Set the import options:

    1. Generate preview links: Check this option to generate preview links for all imported pages. You can then send these links to translators or reviewers so they can proofread the translations.
    2. Delete previous localizations before import: Check this option to delete old translations before importing new ones.
    3. Import as default language: Check this option if you want to overwrite the default language, e. g. after copying a tree.
  6. Select the file to be imported (XML) from your local hard drive.
  7. Click on Upload to start the import. Now the localized data is written to the appropriate database tables. Upon completion you will see a message on the bottom telling you how many data sets have been imported.

Note: Make sure the file to be imported is well-formed XML. If setup correctly translation tools will not modify or corrupt the XML. Anyway, sometimes translators insert non-standard entities into the XML, e.g. &reg; for ® leading to XML parsing errors. Just substitute the entities with their original character before import and everything works fine.

Command Line Interface (CLI) 

Command Line Interface (CLI) The L10N Manger also offers two command line interfaces to export and import content in CAT XML or Excel XML format. To use the CLI you have to create a TYPO3 BE user named _cli_user. CLI for export To find out more about the export interface call the CLI with --help as argument.

php cli_dispatch.phpsh l10nmgr_export –-help

Property: Description:
-s Silent operation, will only output errors and important messages.
--silent Same as -s.
--ss Super silent, will not even output errors or important messages.
--format

Format for export of tranlatable data, supported are:

  • CATXML = XML for translation tools (default)
  • EXCEL = Microsoft XML format
--config Localization Manager configurations. UIDs of the localization manager configurations to be used for export. Comma seperated values, no spaces. Default is EXTCONF which means values are taken from extension configuration.
--target Target languages UIDs for the target languages used during export. Comma seperated values, no spaces. Default is 0. In that case UIDs are taken from extension configuration.
--workspace Workspace ID UID of the workspace used during export. Default = 0
--hidden

Do not export hidden content, the values can be:

  • TRUE = Hidden content is skipped
  • FALSE = Hidden content is exported (default).
--updated

Export only new/updated content, the values can be:

  • TRUE = Only new/updated content is exported
  • FALSE = All content is exported (default)
--check-export Check for already exported content The values can be: • TRUE = Check if content has already been exported. • FALSE = Don't check, just create a new export (default).
--help Show help.
-h Same as –help.

Example php cli_dispatch.phpsh l10nmgr_export --format=CATXML --config=3 --target=1 –hidden=FALSE

CLI for import 

To find out more about the import interface call the CLI with --help as argument. The CLI for import of translations only supports the CAT XML format.

php cli_dispatch.phpsh l10nmgr_import –-help

Property: Description:
-s Silent operation, will only output errors and important messages.
--silent Same as -s.
--ss Super silent, will not even output errors or important messages.
--task

The task to execute, the values can be:

  • importString = Import a XML string
  • importFile = Import a XML file
  • preview = Generate a preview of the source from a XML string
--preview Preview flag Set to 1 in case of preview, 0 otherwise. Defaults to 0.
--string XML string to import
--file Import file Path to the file to import. Can be XML or ZIP archive. If both XML string and import file are not defined, will import from FTP server (if defined).
--server Server link for the preview URL.
--importAsDefaultLanguage

Import as default language. If set this setting will overwrite the default language during the import.

  • TRUE = Content will be imported as default language.
  • FALSE = Content will be imported as translation (default).
--help Show help.
-h Same as –help.

Example

php cli_dispatch.phpsh l10nmgr_import –-task=importFile –-preview=0 -–file=translated-content.xml

FAQ 

Q: When I download the localization package and open the XML file, my XML editor fails (Error: encoding is not correct UTF-8). What can I do?
A: The reason might be a database and/or configuration problem. Check the TYPO3 configuration for UTF-8 database support. You might also want to set TYPO3_CONF_VARS[BE][forceCharset] = utf-8, and check [SYS][multiplyDBfieldSize] and [SYS][UTF8filesystem]. (See http://wiki.typo3.org/index.php/UTF-8_support for more information). Localization Manager assumes that you are using UTF-8 (which is the most highly recommended for multilingual websites).
Q: I get the error message “Call-time pass-by-reference has been deprecated...” under PHP5. What can I do?
A: Add php_value allow_call_time_pass_reference 1 to your .htaccess file.
Q: My exported files are not valid XML. What can I do?
A: Problem is mainly due to nasty bodytext fields or other database fields where editors are allowed to insert HTML code. Try to use Tidy to clean the contents of theses fields. Or use an XML editor and fix the errors manually ;-)

Prerequisites 

Precondition is a proper multi-language setup of TYPO3 and correct UTF8 environment is suggested. The key concept of the extension is that you need to set up the required “L10N Configuration” Records. These records define what content should be included for the translation work. (See section Creating a Localization Manager Configuration)

Rights and permissions 

The basics about the Rights and Permissions concepts of TYPO3 can be found in the “Getting started” document:

For some advanced options, see the “MOD” section in “doc_core_tsconfig”:

Note that for exporting/importing localized data the user needs write access to the affected database tables e.g. pages, pages_language_overlay and tt_content. Furthermore, s/he needs access to the languages to be imported.

Database operations 

The extension uses the TYPO3 API for all database operation to insure data integrity and consistency.

FAQ 

No questions yet.

Options 

Configuration options available during installation of extension:

  • Enable hidden languages (enable_hidden_languages): Decide whether to make available hidden system languages for export/import.
  • Send email notification (enable_notification): Send email otification upon completion of export/import via CLI.
  • Enable FTP upload (enable FTP): Use this for uploading exported files to translation service providers' FTP server. Provide login credentials below.
  • L10N Manager configurations (l10nmgr_cfg): List uids of configuration records for automation of export via CLI script. Use a comma for separating multiple uids.
  • L10N Manager target languages: List of uids of sys_languages for automated export for multiple target languages via CLI

  • Email address: for notification emails in CLI mode

    • Email addres (email_sender): The email address of the sender.
    • Email address (email_recipient): Email address of the recipient, e.g. translator@lsp.com.
    • Organisation (email_sender_organisation): The name of the sender's organisation, e.g. Your Company.
    • Attachment (email_attachment): Attach exported files to notification email.

  • FTP server details

    • FTP server address (ftp_server): The FTP server address where l10nmgr exports should be saved, e.g. ftp.yourdomain.com.
    • FTP server upload path (ftp_server_path): Path o nFTP server where to upload exports.
    • FTP server login (ftp_server_username): The username of your FTP account..
    • FTP server password (ftp_server_password): The password of your FTP account.

  • CLI options

    • Parallel import jobs (service_children): Maximum number of parallel import jobs (processes) (Default = 2)
    • User name for CLI authentication (service_user)
    • Password for CLI authentication (service_pwd)
    • Encryption key for CLI authentication (service_enc): Encryption key for CLI authentication

Other helpful extensions: 

Language visibility (languagevisibility):
Enables multilevel fallback and exception in visibility of content elements.
Language detection (rlmp_language_detection):
Detects the visitors preferred language and redirects to the localized pages accordingly.

FAQ 

Nothing here yet.

Hooks 

Name Method
savePreProcess processBeforeSaving
savePostProcess processAfterSaving
exportCatXmlPreProcess processBeforeExportingCatXml
exportExcelXmlPreProcess processBeforeExportingExcelXml
transformation transform_rte
transformation transform_db

Support 

The extension is maintained by a team:

  • Daniel Zielinski (Loctimize GmbH – www.loctimize.com)
  • Markus Friedrich (dkd Internet Service GmbH – www.dkd.de)
  • Daniel Pötzinger (AOE media GmbH – www.aoe.com)
  • Kasper Skårhøj

Please use http://forge.typo3.org/projects/show/extension-l10nmgr for bug reports and feature requests. For implementation and user support as well as support with translation technologies please contact support@loctimize.com.

Training 

Training for localization project managers and translators is provided by Loctimize GmbH. Training courses for TYPO3 localization managerment and translation can be provided both onsite and online in English, German and French. For further information please contact Daniel Zielinski (support@loctimize.com) or visit http://www.loctimize.com.

Known problems 

  • Performance issues in the context of very large websites during export & import of translations. Temporary solution

is to increase the maximum execution time of PHP scripts (php.ini) and Apache processes (httpd.conf). Another option is to split the export/import files into smaller chunks. Just make sure that you have the head section in the XML and that you don't cut the <pageGrp> element.

  • FAL compatibility issues in version 6.2: Exporting file references and meta data for translation is currently not

possible as FAL uses a different mechanism for storing and localizing data. This results sometimes in duplicated images in the frontend apart from the meta data not being translated. Tip: Don't select tables related to sys_file_references for export. The issue will be addressed during a code sprint in October 2014.

Note: Please contact info@loctimize.com if you are interested in sponsoring the next code sprint.

TYPO3 Forge: http://forge.typo3.org/projects/show/extension-l10nmgr