datamints locallang builder

Version: 14.0
Language: en
Authors: Mark Weisgerber
Email: mark.weisgerber@outlook.de / m.weisgerber@datamints.com
License: Please see file LICENSE.txt

The extension "datamints_locallang_builder" offers a backend module for translating and modifying local language files of active extensions. It is also possible to use an independent translation provider such as Azure or DeepL

TYPO3

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

Community Documentation

This documentation is community documentation for the TYPO3 extension datamints locallang builder

It is maintained as part of this third party extension.

If you find an error or something is missing, please: Report a Problem

Extension Manual

This documentation is for the TYPO3 extension datamints_locallang_builder.

For Contributors

You are welcome to help improve this guide. Just click on "Edit me on GitHub" on the top right to submit your change request.

Table of Contents

Installation

Install the extension with the TYPO3 extension manager
Add the static TypoScript to your Site template
Optional: Define at least one api-key to either azure, deepl or google translate (/Configuration/TypoScript/constants.typoscript)

Configuration

You don't have to include a Static Typoscript Template. Everything loads automatically in backend context

The extension is usable without any custom configuration. If you want to use an auto-translation-provider, you have to enter your own API-Key and flag the provider active.

Example Azure Cloud

To use azure as translation-provider, enter this:

module.tx_datamintslocallangbuilder_tools_datamintslocallangbuildertranslate {
  settings {
    providers {
      azure {
         active = 1
         key = YOUR_KEY
      }
    }
  }
}

Note

To get your API-Key follow this Link: https://docs.microsoft.com/en-us/azure/cognitive-services/Translator/translator-how-to-signup . It's a bit complicated at first, but it's worth it. Insert this API-Key in the "YOUR_KEY" Field in the typoscript configuration example above.

Example DeepL

To use DeepL as translation-provider, enter this:

module.tx_datamintslocallangbuilder_tools_datamintslocallangbuildertranslate {
  settings {
    providers {
      deepl {
         active = 1
         key = YOUR_KEY
      }
    }
  }
}

Note

DeepL is probably the easiest provider to set up. Simply register and call https://www.deepl.com/pro-account/plan . You need the "Authentificationkey". Insert this API-Key in the "YOUR_KEY" Field in the typoscript configuration example above.

Example Google

To use Google as translation-provider, enter this:

module.tx_datamintslocallangbuilder_tools_datamintslocallangbuildertranslate {
  settings {
    providers {
      google {
         active = 1
         key = YOUR_KEY
      }
    }
  }
}

Note

Get your API by calling: https://console.cloud.google.com/apis/api/translate.googleapis.com/credentials . Login to the Google Console and add a API-Key. Insert this API-Key in the "YOUR_KEY" Field in the typoscript configuration example above.

TypoScript Reference

azure.url

Datatype: string
Default: https://api.cognitive.microsofttranslator.com/translate

There should be no need to modify this value. It's the api-host for azure.

azure.version

Datatype: string
Default: 3.0

API-Version number for azure.

azure.key

Datatype: string
Default: <empty>

Your API-Key for Azure.

azure.area

Datatype: string
Default: global

Your defined area, defined in the azure console.

azure.active

Datatype: int
Default

Flag, if this provider is active. Keep in mind to select not more than one provider.

deepl.url

Datatype: string
Default: https://api-free.deepl.com/v2/translate

There should be no need to modify this value. It's the api-host for Deepl.

deepl.version

Datatype: string

Not in use by DeepL

deepl.key

Datatype: string
Default: <empty>

Your API-Key for DeepL.

deepl.area

Datatype: string

Not in use by DeepL

deepl.active

Datatype: int
Default

Flag, if this provider is active. Keep in mind to select not more than one provider.

google.url

Datatype: string
Default: https://www.googleapis.com/language/translate

There should be no need to modify this value. It's the api-host for Google.

google.version

Datatype: string
Default: v2

API-Version number for azure

google.key

Datatype: string
Default: <empty>

Your API-Key for Google.

google.area

Datatype: string

Not in use by Google.

google.active

Datatype: int
Default

Flag, if this provider is active. Keep in mind to select not more than one provider.

excludedExtensions

Datatype: string
Default: datamints_locallang_builder

Comma-separated list of extension keys to be excluded from being displayed.

For Editors

You can access the "Locallang Builder" Menu-Item from the TYPO3-Backend. It's listed in "Admin-Tools".
The first loading of this module may take a short moment, because all your active extensions are getting scanned and their locallang-files mapped into models.
After the loading-process you can see all your active extensions on the left side. Expand one menu-item and select your desired locallang-file.
Now you should see all translations collapsed in the content-area. Click on one entry to expand it. Every entry should have one default-language (EN) and if available, one or more translations (e.g. DE, FR, HU)
You can define a comment for the default-language, which will be inserted into the locallang.xlf export file.
For non-default-languages you can trigger the auto-translate function when configured in typoscript. The text-value for the default-language will be translated and saved to the language you selected.
All changes are saved automatically after 4 seconds, so you don't have to watch out if you saved everything.
At the bottom of the translation you can also have another language created for this entry.
Completely new keys can be created using the action bar. A modal window will open in which you define the value of the standard language and into which language this value should be translated.
When you are done with everything, you can trigger an export in the action bar. Here you can choose where the export should be saved.

It is possible for this export to overwrite the extension files directly or to use an intermediate directory. If you are unsure, you can also have a backup of the previous translations made.

If you modify something in a locallang file at file level, please make sure that you then click on "Reimport" in the panel on the left so that the content is reloaded.

FAQ

Q: Some extensions are not listed

A: Only active extensions are shown. Perhaps the missing extension has no translations or these do not comply with the standard, e.g. because they use a different file extension or the content could not be read

Q: I can't use the auto-translate function. Whats wrong?

A: You have to set a API-Key in the Typoscript-Template for your desired provider. You also have to set the "active" field to 1 if a key is entered.

Q: Where to get the API-Key for Azure?

A: See https://github.com/datamintsGmbH/datamints_locallang_builder/blob/master/Documentation/Configuration/Index.rst#example-azure-cloud

Q: Where to get the API-Key for DeepL?

A: See https://github.com/datamintsGmbH/datamints_locallang_builder/blob/master/Documentation/Configuration/Index.rst#example-deepl

Q: Where to get the API-Key for Google Translate?

A: See https://github.com/datamintsGmbH/datamints_locallang_builder/blob/master/Documentation/Configuration/Index.rst#example-google

Developer Corner

If you need to modify the templates or other stuff, you can initialize the git submodule in /Resources/Public/VueSources.
- The Submodule is fetched from https://github.com/datamintsGmbH/datamints_locallang_builder_vue
Then you have to run "npm install" to load all dependencies.
To build the "VueGenerated" files you have to run a Node-Script, see /Resources/Public/VueSources/package.json for possible script-names, e.g. "npm run watchProd"

Please be aware: See "datamints_locallang_builder/LICENSE.txt" before copying or using the 3rd party libraries included in this submodule. Some of them are licenced only for this purpose.

Hooks

Currently I don't see a requirement to add hooks, so please tell me if you need a possibility to use a hook somewhere.

Vue-Frontend

All source-files can be found in /Resources/Public/VueSources

The project was created with vue-cli, so you'll need to run a node script to compile the source-files and styles, which are dumped in /Resources/Public/VueGenerated

Change log

Version 12.5.1

[FEATURE] Add formality options for DeepL

Version 12.5.0

[TASK] Removed annotation for route to prevent crash with new symfony update
[TASK] changed default value of the approved field to true
[BUG] Implemented backwards compatability for php8.2
[TASK] Added PHP Dependency for composer
[TASK] Deleted some unnecessary icons
[TASK] Added icon for chinese

Version 12.4.2

[BUG] Fixed a bug that occurred when you wanted to overwrite a locallang file, but then only the main language was saved in the correct folder in the export

Version 12.4.1

[FEATURE] respect the feature to overwrite language files in ext_localconf.php - https://docs.typo3.org/m/typo3/reference-coreapi/12.4/en-us/ApiOverview/Localization/ManagingTranslations.html?highlight=locallangxmloverride#custom-translations
[FEATURE] added TYPO3 12 support
[TASK] dropped TYPO3 11 support

Version 1.1.1

[BUGFIX] Fixed php warning when using PHP 8.1 (thx @nhovratov)

Version 1.1.0

[TASK] Reduced header size
[TASK] Increased loading time when resetting everything
[TASK] Updated docs
[BUG] Removed static templates to autoload the typoscript in backend context. So we prevent missing templates when using a multi domain microsite system

Version 1.0.20

[HOTFIX] Added cdata-node-compatibility for Target-Elements

Version 1.0.19

[Feature] Added Support for CDATA-Nodes
[Bug] Fixed autoload issue for some TYPO3 10.x instances when using alternative classes

Version 1.0.18

[Feature] Added TYPO3 11.x Support
[Bug] Added encoding when creating source-texts to prevent invalid file-content
[Bug] Fixed country-flag-paths for cs & ja
[Bug] Implemented security check to prevent error on export when the default-language is missing for one entry

Version 1.0.17

[Feature] You can now exclude extensions from being displayed/scanned
[Feature] TS constants can now be maintained in the Constant Editor
[Stylings] Fixed some small style issues

Version 1.0.16

Changed module icon
Removed unnecessary "required"-attribute from language-fields. It is now possible to create new keys only with the default-language.
Improved Layout for "New Key"-View
Set "Create backup" initially to false

Version 1.0.15

new feature: Display ViewHelper Snippets for Fluid (+ inline) & Extbase-Integration

Version 1.0.14

renamed wrong file name from DeepLProvider to DeeplProvider. It didnt match the class name before

Version 1.0.13

added option to delete the whole translation-record
moved translation-action-area to the top of the collapse-button to save some space

Version 1.0.12

hide Objects in List-View
removed the disable-function when waiting for a response
Changed the appearance of the auto-save overlay so that it is no longer so intrusive

Version 1.0.11

added lazy annotations for a much better performance
changed repo query to generic constraint system to avoid storage-restriction
compiled the vue project (improved error-handling for invalid locallang-attributes)
Disabled the language recognition by xliff target-language attribute because we cant always rely on the correct-value. Otherwise some files cannot be scanned. (thx Wolfang Wagner for the hint)

Version 1.0.10

Replaced "is_file" checks with "is_dir" checks. (Thanks to @dbunkerd )

Version 1.0.9

fixed read-process for the approved attribute (thanks @opi99 https://github.com/datamintsGmbH/datamints_locallang_builder/issues/3)

Version 1.0.8

fixed missing fields for "approved" and "xml:space" in the export-function
removed old deprecated tca-files when the extension had a different nam

Version 1.0.7

Added fallback when a file does not contain a target-language attribute while scanning those. Instead we fetch the language code from the filename
hotfix for wrong format of api-request;
changed order of alert-component when a critical error occurs
Modified the locallang-prefixes to match the ident "datamintslocallangbuilder" instead of the old extension ident "locallangbuilder"
Replaced all places where "locallangbuilder" appeared (Thanks to @opi99 )

Version 1.0.6

Hotfix for invalid flag-paths (en.svg etc.)

Version 1.0.5

Switched to the native TYPO3 Logging instead of own implementation
fixed some documentation-stuff
locked auto-translate when there is no provider configured. Instead a info will be given.

Version 1.0.4

Added clear cache on load-flag to prevent autoloader-bugs
Fixed some documentation-issues with rst-format
Removed dummy-Boxes for statistics (not finished yet)
some misc stuff

Version 1.0.3

Release of the first stable version.