[BUGFIX] Fix wrong codeblock type in rst files
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Important-80241-ExtFormSimplifyTranslationHandling.rst
1 .. include:: ../../Includes.txt
2
3 =================================================================
4 Task: #80241 - EXT:form simplify translation handling
5 =================================================================
6
7 See :issue:`80241`
8
9 Description
10 ===========
11
12 If an integrator wants to add translations for new form elements he can only
13 define a new translation file which must contain all translation keys.
14 This patch makes it possible to define multiple translation files.
15
16 Before this patch:
17
18 .. code-block:: yaml
19
20 TYPO3:
21 CMS:
22 Form:
23 prototypes:
24 standard:
25 formElementsDefinition:
26 Form:
27 renderingOptions:
28 translation:
29 translationFile: 'EXT:form/Resources/Private/Language/locallang.xlf'
30
31 After this patch:
32
33 .. code-block:: yaml
34
35 TYPO3:
36 CMS:
37 Form:
38 prototypes:
39 standard:
40 formElementsDefinition:
41 Form:
42 renderingOptions:
43 translation:
44 translationFile:
45 10: 'EXT:form/Resources/Private/Language/locallang.xlf'
46 20: 'EXT:my_ext/Resources/Private/Language/locallang.xlf'
47
48 The translation keys will be searched within the referenced files.
49 The search order is from the key with the highest number to the lowest.
50 If a translation key is found within one of these files the search will stop.
51
52 This makes it possible to only define new keys within the custom translations
53 and use the default form translations as well.
54 The default settings keep the translationFile property as string because
55 of backward compatibility.
56
57 Before this patch the "BaseFormElementMixin" inherits the "translationSettingsMixin".
58 Thus, the "renderingOptions.translation..." are copied to each form element.
59 This is inconvenient if an integrator defines his own prototype which inherits from
60 the standard prototype because he must redefine the "renderingOptions.translation..."
61 options for each form element.
62
63 Since there already is a fallback strategy to the "renderingOptions.translation..."
64 options from the root form element - if this option is not set within the
65 child form elements - we can simply apply the "translationSettingsMixin"
66 to the "Form" element and remove it from the "BaseFormElementMixin".
67 Now, the rendering options are only set for the "Form" element and rules
68 as a prototype wide frontend translation setting.
69
70 This patch adds a fallback for the form engine translation if there is no
71 "translationFile" setting within the "FormEngine" option.
72
73 .. code-block:: yaml
74
75 TYPO3:
76 CMS:
77 Form:
78 prototypes:
79 standard:
80 formEngine:
81 translationFile:
82 10: 'EXT:form/Resources/Private/Language/Database.xlf'
83 20: 'EXT:ext_form_example1484232130/Resources/Private/Language/Database.xlf'
84
85 Now, there is one prototype wide form engine (plugin settings) translation setting.
86
87
88 Summary
89 -------
90
91 With this patch, an integrator has prototype wide translation settings
92 for the 4 aspects of the form framework. Furthermore, the integrator is
93 able to define multiple translation files to avoid copying the whole
94 default translation files or using locallangXMLOverride.
95
96 .. code-block:: yaml
97
98 TYPO3:
99 CMS:
100 Form:
101 formManager:
102 selectablePrototypesConfiguration:
103 1484232130:
104 translationFile:
105 # translations for the form managers "new form" modal
106 10: 'EXT:form/Resources/Private/Language/Database.xlf'
107 20: 'EXT:my_ext/Resources/Private/Language/Database.xlf'
108
109 prototypes:
110 <prototypeName>:
111 formEditor:
112 translationFile:
113 # translations for the form editor
114 10: 'EXT:form/Resources/Private/Language/Database.xlf'
115 20: 'EXT:my_ext/Resources/Private/Language/Database.xlf'
116
117 formEngine:
118 translationFile:
119 # translations for the form plugin (finisher overrides)
120 10: 'EXT:form/Resources/Private/Language/Database.xlf'
121 20: 'EXT:my_ext/Resources/Private/Language/Database.xlf'
122
123 formElementsDefinition:
124 Form:
125 renderingOptions:
126 translation:
127 translationFile:
128 # translations for the frontend
129 10: 'EXT:form/Resources/Private/Language/locallang.xlf'
130 20: 'EXT:my_ext/Resources/Private/Language/locallang.xlf'
131
132
133 Impact
134 ======
135
136 Easier to use, less maintenance.
137
138 .. index:: Backend, Frontend, ext:form