Difference between revisions of "Debugging a translation"

From Joomla! Documentation

(New page: Joomla supports some useful debugging mechanisms that can make it easier to locate untranslated strings and diagnose problems with language translations in installed extensions. ==== Debu...)
 
m (clear template)
(13 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
<noinclude>{{JSplit}}
 +
 +
{{notice|Is this version specific? Are there differences in debugging from 1.5, 2.5 and 3.x? If so, let's split it up or mark it better.}}  </noinclude>
 +
 
Joomla supports some useful debugging mechanisms that can make it easier to locate untranslated strings and diagnose problems with language translations in installed extensions.
 
Joomla supports some useful debugging mechanisms that can make it easier to locate untranslated strings and diagnose problems with language translations in installed extensions.
  
 
==== Debug Language ====
 
==== Debug Language ====
[[Image:]]You activate language debugging via the Administration Back-end by going into Global Configuration and clicking on the System tab. Find the Debug Language field, change the value to “Yes” and save your changes.
+
[[Image:global-config-language-debug.png|right]]You activate language debugging via the Administration Back-end by going into Global Configuration and clicking on the System tab. Find the Debug Language field, change the value to “Yes” and save your changes.
  
 
With this option active all translatable strings are shown surrounded with special characters that indicate their status
 
With this option active all translatable strings are shown surrounded with special characters that indicate their status
 
+
{{clear}}
 
+
{| class="wikitable sortable"
{| class="prettytable"
+
! Code
| <center>●Joomla CMS●</center>
+
! Status
 +
|-
 +
| ●Joomla CMS●
 
| ''(text surrounded by bullets)'' indicates that a match has been found in the language definition file and the string has been translated.
 
| ''(text surrounded by bullets)'' indicates that a match has been found in the language definition file and the string has been translated.
  
 
|-
 
|-
| <center>??Joomla CMS??</center>
+
| ??Joomla CMS??
 
| ''(text surrounded by pairs of question marks)'' indicates that the string is translatable but no match was found in the language definition file.
 
| ''(text surrounded by pairs of question marks)'' indicates that the string is translatable but no match was found in the language definition file.
  
 
|-
 
|-
| <center>Joomla CMS</center>
+
| Joomla CMS
 
| ''(text with no surrounding characters)'' indicates that the string is not translatable.
 
| ''(text with no surrounding characters)'' indicates that the string is not translatable.
  
Line 25: Line 31:
 
With this option active all screens have additional debugging information at the end of each page. Currently this includes
 
With this option active all screens have additional debugging information at the end of each page. Currently this includes
  
* Profile information. This is the amount of time taken to execute code up to various mark points in the code.
+
* '''Profile information.'''  This is the amount of time taken to execute code up to various mark points in the code.
* Memory usage. The amount of system RAM used.
+
* '''Memory usage.'''  The amount of system RAM used.
* SQL queries executed. All of the SQL queries executed in the process of building the page.
+
* '''SQL queries executed.'''  All of the SQL queries executed in the process of building the page.
* Language files loaded. A list of all the language files loaded in the process of building the page, including full path information. This can be useful to check that the expected files have been loaded. The number after each file path is the number of times that the file was referenced.
+
* '''Language files loaded.'''  A list of all the language files loaded in the process of building the page, including full path information. This can be useful to check that the expected files have been loaded. The number after each file path is the number of times that the file was referenced.
* Untranslated strings diagnostic. A list of all the untranslated strings found and the likely file location given where the JText call was made.
+
* '''Untranslated strings diagnostic.'''  A list of all the untranslated strings found and the likely file location given where the JText call was made.
* Untranslated strings designer. A list of all the untranslated strings found but listed in a KEY=Value format so they can be copy-pasted directly into a language definition file (INI).
+
* '''Untranslated strings designer.'''  A list of all the untranslated strings found but listed in a KEY=Value format so they can be copy-pasted directly into a language definition file (INI).
  
 
==== Debug Plugin ====
 
==== Debug Plugin ====
[[Image:]]This system plugin controls what is displayed when debugging is activated in '''Global Configuration'''. It is enabled by default. You can access the parameters for the plugin from '''Extensions → Plugin Manager'''. Locate the “System - Debug” plugin and click on it. There are three settings of interest to translators.
+
[[Image:debug-plugin.png|right]]This system plugin controls what is displayed when debugging is activated in '''Global Configuration'''. It is enabled by default. You can access the parameters for the plugin from '''Extensions → Plugin Manager'''. Locate the “System - Debug” plugin and click on it. There are three settings of interest to translators.
  
* '''Display loaded language files''' (New in Joomla 1.5.4) Determines whether or not to display the language files that have been loaded to generate the page. This has two modes: diagnostic and designer. Diagnostic mode displays the untranslated string and the likely file location whether the '''JText''' call was made. Designer mode displays the strings in a format that can be copy-pasted into a .ini language file (displays the list in ''KEY=String'' format).
+
* '''Display loaded language files'''. If set to “Yes” then the debug information will include a list of the language files that were requested as the current page was being generated.
* '''Display undefined language strings.''' Determines whether or not to include undefined language strings in the debug information.
+
* '''Display undefined language strings.'''  If set to “diagnostic mode” then a list of untranslated strings and the location of the file containing the call to '''JText''' is included in the debug information. If set to “designer mode” then a list of untranslated strings in a format that can be copy-pasted directly into a language definition file is included in the debug information.  That is, it displays the list in KEY=String format. If set to “All modes” then both the diagnostic mode and designer mode lists are included in the debug information.
* '''Strip Key Prefix''' (New in Joomla 1.5.4) When untranslated strings are displayed in Designer mode, this allows you to strip a prefix from the string to form the key. This is useful if the designer uses a common prefix for their extensions when using '''JText''' methods.  
+
* '''Strip Key Prefix'''. Only used when '''Display undefined language strings''' is set to “Designer mode” or "All modes". This allows you to strip a prefix from the string to form the key. This is useful if the designer uses a common prefix for their extensions when using JText methods.  See example below.
  
 
Note that the display of untranslated strings will only display the value passed to the appropriate '''JText''' method. For example, with the following code:  
 
Note that the display of untranslated strings will only display the value passed to the appropriate '''JText''' method. For example, with the following code:  
 
+
<source lang="php">
echo JText::_( 'Reports Import Configuration' );
+
echo JText::_( 'Reports Import Configuration' );
 
+
</source>
 
If untranslated, Designer mode will display this as:  
 
If untranslated, Designer mode will display this as:  
  
Line 54: Line 60:
  
 
Note that the path shown is only a best guess based on a call to the PHP ''debug_backtrace'' function. Sometimes it is accurate, sometimes it is not and there are also cases where no file could be determined. In those cases you have to use your best judgement.
 
Note that the path shown is only a best guess based on a call to the PHP ''debug_backtrace'' function. Sometimes it is accurate, sometimes it is not and there are also cases where no file could be determined. In those cases you have to use your best judgement.
 +
<noinclude>[[Category:Tutorials]][[Category:Language Development]]</noinclude>

Revision as of 06:39, 26 June 2013

Split-icon.png
Split Page into Specific Joomla! Versions - J2.5 and 3.x

It has been suggested that this article or section be split into specific version Namespaces. (Discuss). If version split is not obvious, please allow split request to remain for 1 week pending discussions. Proposed since 10 years ago.


Info non-talk.png
General Information

Is this version specific? Are there differences in debugging from 1.5, 2.5 and 3.x? If so, let's split it up or mark it better.

Joomla supports some useful debugging mechanisms that can make it easier to locate untranslated strings and diagnose problems with language translations in installed extensions.

Debug Language[edit]

Global-config-language-debug-en.png

You activate language debugging via the Administration Back-end by going into Global Configuration and clicking on the System tab. Find the Debug Language field, change the value to “Yes” and save your changes.

With this option active all translatable strings are shown surrounded with special characters that indicate their status

Code Status
●Joomla CMS● (text surrounded by bullets) indicates that a match has been found in the language definition file and the string has been translated.
??Joomla CMS?? (text surrounded by pairs of question marks) indicates that the string is translatable but no match was found in the language definition file.
Joomla CMS (text with no surrounding characters) indicates that the string is not translatable.

Debug System[edit]

Additional language debugging information can be obtained by activating system debugging. This is done by going into Global Configuration and clicking on the System tab. Find the Debug System field, change the value to “Yes” and save your changes.

With this option active all screens have additional debugging information at the end of each page. Currently this includes

  • Profile information. This is the amount of time taken to execute code up to various mark points in the code.
  • Memory usage. The amount of system RAM used.
  • SQL queries executed. All of the SQL queries executed in the process of building the page.
  • Language files loaded. A list of all the language files loaded in the process of building the page, including full path information. This can be useful to check that the expected files have been loaded. The number after each file path is the number of times that the file was referenced.
  • Untranslated strings diagnostic. A list of all the untranslated strings found and the likely file location given where the JText call was made.
  • Untranslated strings designer. A list of all the untranslated strings found but listed in a KEY=Value format so they can be copy-pasted directly into a language definition file (INI).

Debug Plugin[edit]

Debug-plugin-en.png

This system plugin controls what is displayed when debugging is activated in Global Configuration. It is enabled by default. You can access the parameters for the plugin from Extensions → Plugin Manager. Locate the “System - Debug” plugin and click on it. There are three settings of interest to translators.

  • Display loaded language files. If set to “Yes” then the debug information will include a list of the language files that were requested as the current page was being generated.
  • Display undefined language strings. If set to “diagnostic mode” then a list of untranslated strings and the location of the file containing the call to JText is included in the debug information. If set to “designer mode” then a list of untranslated strings in a format that can be copy-pasted directly into a language definition file is included in the debug information. That is, it displays the list in KEY=String format. If set to “All modes” then both the diagnostic mode and designer mode lists are included in the debug information.
  • Strip Key Prefix. Only used when Display undefined language strings is set to “Designer mode” or "All modes". This allows you to strip a prefix from the string to form the key. This is useful if the designer uses a common prefix for their extensions when using JText methods. See example below.

Note that the display of untranslated strings will only display the value passed to the appropriate JText method. For example, with the following code:

echo JText::_( 'Reports Import Configuration' );

If untranslated, Designer mode will display this as:

# /administrator/components/com_reports/views/reports/tmpl/default.php
REPORTS IMPORT CONFIGURATION=Reports Import Configuration

If the Strip Key Prefix is set to "Reports", then the display would change slightly to:

# /administrator/components/com_reports/views/reports/tmpl/default.php
REPORTS IMPORT CONFIGURATION=Import Configuration

Note that the path shown is only a best guess based on a call to the PHP debug_backtrace function. Sometimes it is accurate, sometimes it is not and there are also cases where no file could be determined. In those cases you have to use your best judgement.