Skip to content

Commit da3362d

Browse files
dregaddregad
committedFeb 6, 2013
Documentation: custom fields localization
The indications in the Custom Fields localization section contained an incorrect reference to lang_get_current() to determine the current language in custom_strings_inc.php. Using this function will cause the code to return incorrect translations if the default language is different from English. Fixes #10118
·
release-2.27.1release-1.3.0-beta.1
1 parent 562db4f commit da3362d

File tree

1 file changed

+100
-52
lines changed

1 file changed

+100
-52
lines changed
 

‎docbook/Admin_Guide/en-US/Customizing.xml

+100-52
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,18 @@
7070

7171
<itemizedlist>
7272
<listitem>
73-
<para>Caption variable name (eg: This is the value that is
74-
supplied to lang_get() API, or displayed as-is if not found in
75-
language file). This should not include any space or
76-
any character that would be an invalid PHP identifier.
77-
</para>
73+
<para>Caption variable name.
74+
This value is supplied to the lang_get() API; it is
75+
therefore mandatory to set this to a
76+
<ulink url="http://php.net/language.variables.basics.php">valid PHP identifier</ulink>
77+
(i.e. only letters, numbers and underscores; no spaces)
78+
if you intend to translate the field label
79+
(see <xref linkend="admin.customize.customfields.localize" />).
80+
</para>
81+
<note><para>If the specified variable is not found in the
82+
language files or in custom strings, then it will be
83+
displayed as-is.
84+
</para></note>
7885
</listitem>
7986
<listitem>
8087
<para>Custom field type (string, numeric, float,
@@ -86,7 +93,7 @@
8693
<para>Type 'enumeration' is used when a user selects one entry from a list. The user interface for such type is a combo-box.</para>
8794
<para>Type 'email' is used for storing email addresses.</para>
8895
<para>Type 'checkbox' is like enumeration but the list is shown as checkboxes and the user is allowed to tick more than one selection. The default value and the possible value can contain multiple values like 'RED|YELLOW|BLUE' (without the single quote).</para>
89-
<para>Type 'radio' is like enumeration but the list is shown as radio buttons and the user is allowed to tick on of the options. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'YELLOW'. Note that the default value can't contain multiple values.</para>
96+
<para>Type 'radio' is like enumeration but the list is shown as radio buttons and the user is allowed to tick on of the options. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'YELLOW'. Note that the default value can't contain multiple values.</para>
9097
<para>Type 'list' is like enumeration but the list is shown as a list box where the user is only allowed to select one option. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'YELLOW'. Note that the default value can't contain multiple values.</para>
9198
<para>Type 'multi-selection list' is like enumeration but the list is shown as a list box where the user is allowed to select multiple options. The possible values can be 'RED|YELLOW|BLUE', where the default value can be 'RED|BLUE'. Note that in this case the default value contains multiple values.</para>
9299
<para>Type 'date' is for date values. The default value can be empty, or {tomorrow}, {yesterday}, {next week}, {last week}, {+3 days}, {-2 days}.</para>
@@ -279,36 +286,68 @@
279286
<section id="admin.customize.customfields.localize">
280287
<title>Localizing Custom Field Names</title>
281288

282-
<para>It is possible to localize the label for the custom fields.
283-
This can be as follows:
284-
285-
<itemizedlist>
286-
<listitem><para>Give the custom field a valid variable name
287-
(i.e. start with an alpha character, no spaces, etc) - For
288-
example, we will use "my_start_date" for a custom field of
289-
type "Date" which stores the "Start Date" for working on an
290-
issue.</para></listitem>
291-
<listitem><para>Add the localized string for "my_start_date"
292-
- This can be done by creating custom_strings_inc.php in the
293-
MantisBT root folder and adding the following code to it:
289+
<para>It is possible to localize the custom fields' labels.
290+
This can be done as follows:
291+
292+
<orderedlist>
293+
<listitem>
294+
<para>Define the custom field
295+
(see <xref linkend="admin.customize.customfields.definitions" />),
296+
keeping in mind that its name must be a
297+
<ulink url="http://php.net/language.variables.basics.php">valid PHP identifier</ulink>.
298+
</para>
299+
<para>As an example, we will use
300+
<emphasis>my_start_date</emphasis>
301+
for a custom field of type "Date", storing the date when
302+
work on an issue was initiated.
303+
</para>
304+
</listitem>
305+
<listitem>
306+
<para>Set the localization strings
307+
<itemizedlist>
308+
<listitem><para>In the main MantisBT directory, locate and
309+
edit file <emphasis>custom_strings_inc.php</emphasis>
310+
(create it if it does not exist)
311+
</para></listitem>
312+
<listitem><para>Localize the custom field's label
313+
<emphasis>my_start_date</emphasis> by adding
314+
the following code
294315
<programlisting>
295316
&lt;?php
296-
if ( lang_get_current() == 'german' ) {
297-
$s_my_start_date = 'Start Date XX'; // German translation of Start Date
298-
} else {
299-
# Default (use your preferred language as the default)
300-
$s_my_start_date = 'Start Date';
317+
switch( $g_active_language ) {
318+
case 'french':
319+
$s_my_start_date = 'Date de début';
320+
break;
321+
322+
default:
323+
# Default language, as defined in config_inc.php
324+
# ($g_default_language, English in this case)
325+
$s_my_start_date = 'Start Date';
326+
break;
301327
}
302-
?&gt;</programlisting></para></listitem>
303-
</itemizedlist>
304-
</para>
328+
</programlisting>
329+
<warning><para>Do NOT call
330+
<emphasis>lang_get_current()</emphasis>
331+
from custom_strings_inc.php, as doing so
332+
will reset the active_language, causing the
333+
code to return incorrect translations if the
334+
default language is different from English.
335+
Always use the <emphasis>$g_active_language</emphasis>
336+
global variable instead.
337+
</para></warning>
338+
</para></listitem>
339+
</itemizedlist>
340+
</para>
341+
</listitem>
342+
</orderedlist>
343+
</para>
305344

306-
<note><para>If we would have decided to use start_date as the
307-
name of the custom field, then we have used an already localized
308-
string from MantisBT standard strings. In this case, there is no
309-
need to create the custom_strings_inc.php or to add any strings to
310-
it. To check for standard strings, inspect
311-
lang/strings_english.txt.</para></note>
345+
<note><para>Had we decided to use <emphasis>start_date</emphasis>
346+
as the custom field's name, then it would not have been necessary to
347+
modify custom_strings_inc.php, since MantisBT would have used the
348+
existing, already localized string from the standard language files.
349+
To check for standard strings, inspect lang/strings_english.txt.
350+
</para></note>
312351
</section>
313352

314353
<section id="admin.customize.customfields.defaults">
@@ -546,7 +585,7 @@ functions section.</para>
546585
detected and included by MantisBT code.
547586
<programlisting>
548587
# Note that we don't have to remove the Updater entry from the
549-
localisation file if ( lang_get_current() === 'english' ) {
588+
localisation file if the current language is 'english' ) {
550589
$s_access_levels_enum_string =
551590
'10:Betrachter,25:Reporter,40:Updater,55:Entwickler,60:Senior
552591
Developer,70:Manager,90:Administrator'; }
@@ -657,25 +696,25 @@ functions section.</para>
657696
</para>
658697
</section>
659698

660-
<section id="admin.customize.status">
661-
<title>Customizing Status Values</title>
699+
<section id="admin.customize.status">
700+
<title>Customizing Status Values</title>
662701

663702
<para>This section describes how to add a custom status.
664-
<orderedlist>
665-
<listitem>
703+
<orderedlist>
704+
<listitem>
666705
<para>Define a constant to map the new status to.</para>
667-
<para>In the main mantisbt directory, locate and edit file
706+
<para>In the main MantisBT directory, locate and edit file
668707
<emphasis>custom_constants_inc.php</emphasis>;
669708
(create it if it does not exist)
670709
<programlisting>
671710
&lt;?php
672711
# Custom status code
673712
define( 'TESTING', 60 );
674713
</programlisting>
675-
</para>
676-
</listitem>
714+
</para>
715+
</listitem>
677716

678-
<listitem>
717+
<listitem>
679718
<para>Define the new status in the enumeration, as well as
680719
the corresponding color code.
681720
</para>
@@ -725,9 +764,9 @@ $g_status_colors['<emphasis>testing</emphasis>'] = '#ACE7AE';
725764
<programlisting>
726765
&lt;?php
727766
# Translation for Custom Status Code: <emphasis>testing</emphasis>
728-
switch( lang_get_current() ) {
767+
switch( $g_active_language ) {
729768

730-
french:
769+
case 'french':
731770
$s_status_enum_string = '10:nouveau,20:commentaire,30:accepté,40:confirmé,50:affecté,60:à tester,80:résolu,90:fermé';
732771

733772
$s_testing_bug_title = 'Mettre le bogue en test';
@@ -745,12 +784,21 @@ switch( lang_get_current() ) {
745784
$s_email_notification_title_for_status_bug_testing = 'The following issue is ready for TESTING.';
746785
}
747786
</programlisting>
748-
</para>
749-
</listitem>
787+
<warning><para>Do NOT call
788+
<emphasis>lang_get_current()</emphasis>
789+
from custom_strings_inc.php, as doing so
790+
will reset the active_language, causing the
791+
code to return incorrect translations if the
792+
default language is different from English.
793+
Always use the <emphasis>$g_active_language</emphasis>
794+
global variable instead.
795+
</para></warning>
796+
</para>
797+
</listitem>
750798

751-
<listitem>
799+
<listitem>
752800
<para>Add the new status to the workflow as required.
753-
</para>
801+
</para>
754802
<para>This can either be done from the
755803
Manage Workflow Transitions page
756804
(see <xref linkend="admin.lifecycle.workflow.transitions" />)
@@ -767,11 +815,11 @@ $g_status_enum_workflow[TESTING] ='80:resolved,20:feedback,50:assigned';
767815
$g_status_enum_workflow[RESOLVED] ='90:closed,20:feedback,50:assigned';
768816
$g_status_enum_workflow[CLOSED] ='20:feedback,50:assigned';
769817
</programlisting>
770-
</para>
771-
</listitem>
772-
</orderedlist>
773-
</para>
774-
</section>
818+
</para>
819+
</listitem>
820+
</orderedlist>
821+
</para>
822+
</section>
775823

776824
<section id="admin.customize.customfuncs">
777825
<title>Custom Functions</title>

0 commit comments

Comments
 (0)
Please sign in to comment.