Skip to content

Commit

Permalink
Documentation: custom fields localization
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@dregad
dregad committed Feb 6, 2013
1 parent 562db4f commit da3362d
Showing 1 changed file with 100 additions and 52 deletions.
152 changes: 100 additions & 52 deletions docbook/Admin_Guide/en-US/Customizing.xml
View file
Expand Up @@ -70,11 +70,18 @@

<itemizedlist>
<listitem>
<para>Caption variable name (eg: This is the value that is
supplied to lang_get() API, or displayed as-is if not found in
language file). This should not include any space or
any character that would be an invalid PHP identifier.
</para>
<para>Caption variable name.
This value is supplied to the lang_get() API; it is
therefore mandatory to set this to a
<ulink url="http://php.net/language.variables.basics.php">valid PHP identifier</ulink>
(i.e. only letters, numbers and underscores; no spaces)
if you intend to translate the field label
(see <xref linkend="admin.customize.customfields.localize" />).
</para>
<note><para>If the specified variable is not found in the
language files or in custom strings, then it will be
displayed as-is.
</para></note>
</listitem>
<listitem>
<para>Custom field type (string, numeric, float,
Expand All @@ -86,7 +93,7 @@
<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>
<para>Type 'email' is used for storing email addresses.</para>
<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>
<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>
<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>
<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>
<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>
<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>
Expand Down Expand Up @@ -279,36 +286,68 @@
<section id="admin.customize.customfields.localize">
<title>Localizing Custom Field Names</title>

<para>It is possible to localize the label for the custom fields.
This can be as follows:

<itemizedlist>
<listitem><para>Give the custom field a valid variable name
(i.e. start with an alpha character, no spaces, etc) - For
example, we will use "my_start_date" for a custom field of
type "Date" which stores the "Start Date" for working on an
issue.</para></listitem>
<listitem><para>Add the localized string for "my_start_date"
- This can be done by creating custom_strings_inc.php in the
MantisBT root folder and adding the following code to it:
<para>It is possible to localize the custom fields' labels.
This can be done as follows:

<orderedlist>
<listitem>
<para>Define the custom field
(see <xref linkend="admin.customize.customfields.definitions" />),
keeping in mind that its name must be a
<ulink url="http://php.net/language.variables.basics.php">valid PHP identifier</ulink>.
</para>
<para>As an example, we will use
<emphasis>my_start_date</emphasis>
for a custom field of type "Date", storing the date when
work on an issue was initiated.
</para>
</listitem>
<listitem>
<para>Set the localization strings
<itemizedlist>
<listitem><para>In the main MantisBT directory, locate and
edit file <emphasis>custom_strings_inc.php</emphasis>
(create it if it does not exist)
</para></listitem>
<listitem><para>Localize the custom field's label
<emphasis>my_start_date</emphasis> by adding
the following code
<programlisting>
&lt;?php
if ( lang_get_current() == 'german' ) {
$s_my_start_date = 'Start Date XX'; // German translation of Start Date
} else {
# Default (use your preferred language as the default)
$s_my_start_date = 'Start Date';
switch( $g_active_language ) {
case 'french':
$s_my_start_date = 'Date de début';
break;

default:
# Default language, as defined in config_inc.php
# ($g_default_language, English in this case)
$s_my_start_date = 'Start Date';
break;
}
?&gt;</programlisting></para></listitem>
</itemizedlist>
</para>
</programlisting>
<warning><para>Do NOT call
<emphasis>lang_get_current()</emphasis>
from custom_strings_inc.php, as doing so
will reset the active_language, causing the
code to return incorrect translations if the
default language is different from English.
Always use the <emphasis>$g_active_language</emphasis>
global variable instead.
</para></warning>
</para></listitem>
</itemizedlist>
</para>
</listitem>
</orderedlist>
</para>

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

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

<section id="admin.customize.status">
<title>Customizing Status Values</title>
<section id="admin.customize.status">
<title>Customizing Status Values</title>

<para>This section describes how to add a custom status.
<orderedlist>
<listitem>
<orderedlist>
<listitem>
<para>Define a constant to map the new status to.</para>
<para>In the main mantisbt directory, locate and edit file
<para>In the main MantisBT directory, locate and edit file
<emphasis>custom_constants_inc.php</emphasis>;
(create it if it does not exist)
<programlisting>
&lt;?php
# Custom status code
define( 'TESTING', 60 );
</programlisting>
</para>
</listitem>
</para>
</listitem>

<listitem>
<listitem>
<para>Define the new status in the enumeration, as well as
the corresponding color code.
</para>
Expand Down Expand Up @@ -725,9 +764,9 @@ $g_status_colors['<emphasis>testing</emphasis>'] = '#ACE7AE';
<programlisting>
&lt;?php
# Translation for Custom Status Code: <emphasis>testing</emphasis>
switch( lang_get_current() ) {
switch( $g_active_language ) {

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

$s_testing_bug_title = 'Mettre le bogue en test';
Expand All @@ -745,12 +784,21 @@ switch( lang_get_current() ) {
$s_email_notification_title_for_status_bug_testing = 'The following issue is ready for TESTING.';
}
</programlisting>
</para>
</listitem>
<warning><para>Do NOT call
<emphasis>lang_get_current()</emphasis>
from custom_strings_inc.php, as doing so
will reset the active_language, causing the
code to return incorrect translations if the
default language is different from English.
Always use the <emphasis>$g_active_language</emphasis>
global variable instead.
</para></warning>
</para>
</listitem>

<listitem>
<listitem>
<para>Add the new status to the workflow as required.
</para>
</para>
<para>This can either be done from the
Manage Workflow Transitions page
(see <xref linkend="admin.lifecycle.workflow.transitions" />)
Expand All @@ -767,11 +815,11 @@ $g_status_enum_workflow[TESTING] ='80:resolved,20:feedback,50:assigned';
$g_status_enum_workflow[RESOLVED] ='90:closed,20:feedback,50:assigned';
$g_status_enum_workflow[CLOSED] ='20:feedback,50:assigned';
</programlisting>
</para>
</listitem>
</orderedlist>
</para>
</section>
</para>
</listitem>
</orderedlist>
</para>
</section>

<section id="admin.customize.customfuncs">
<title>Custom Functions</title>
Expand Down

0 comments on commit da3362d

Please sign in to comment.