MoodleDocs - User contributions [en]

User:Dan Stowell

2007-05-12T17:38:05Z

Danstowell:

[http://www.elec.qmul.ac.uk/department/staff/research/dans.htm Dan Stowell]

I've been developing bits and bobs for Moodle for a while - for example:

* '''In Moodle core:'''
** [[IMS Enterprise]] enrolment module
** [[Fields#Latitude.2Flongitude|Latitude/longitude data type]] for database activity
* '''Optional add-ins:'''
** [http://moodle.org/mod/forum/discuss.php?d=50265 MoodleSpeex] voice messaging tool
** [[Jmol filter]]
** [[Jmol resource type]]
** [http://moodle.org/mod/data/view.php?d=13&rid=296 Java Molecular Editor question type]
** [[WebCT migration]] scripts

If you want to know more about me you might like to look at [http://www.mcld.co.uk/cv/quick/ my CV]

Development:Coding

2007-03-05T22:23:24Z

Danstowell: /* General rules */

Any collaborative project needs consistency and stability to stay strong.

These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.

==General rules==

# All code files should use the .php extension.
# All template files should use the .html extension.
# All text files should use Unix-style text format (most text editors have this as an option).
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.
# All existing copyright notices must be retained. You can add your own if necessary.
# Each file should include the main config.php file.
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string(). Never delete strings to ensure backwards compatibility of the language packs is maintained.
# All errors should be printed using print_error() to maximise translation and help for users (it automatically links to the docs wiki).
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Development:Output_functions|output functions]].
# User actions should be logged using the [[Development:Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].
# When generating a HTML link, always make it relative to the full site root, i.e. link to ''$CFG->wwwroot/mod/blonk/view.php?id=99'' rather than just ''view.php?id=99''. This means that your code will work if called by a script in another folder, among other things.

==Coding style==

I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.

1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.

2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)

BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.

define("FORUM_MODE_FLATOLDEST", 1);
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).

function forum_set_display_mode($mode=0) {
global $USER, $CFG;

if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}

5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}

6. Strings should be defined using single quotes where possible, for increased speed.

$var = 'some text without any variables';
$var = "with special characters like a new line \n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.

* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc

8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:

foreach ($objects as $key => $thing) {
process($thing);
}

if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}

9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.

BAD: $b = $a;
GOOD: $b = clone($a);

If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.

==Database structures==

# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[Development:XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.
# '''Never''' make database changes in the STABLE branches. If we did, then users upgrading from one stable version to the next would have duplicate changes occurring, which may cause serious errors.

==Security issues (and handling form and URL data)==

# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from.
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Use data_submitted(), with care. Data must still be cleaned before use.
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
# Any data read from the database must have [[Developer:Slashes|addslashes()]] applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
# Do not use data from $_SERVER if you can avoid it. This has portability issues.
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.

[[Category:Developer]]

[[es:Manual de Estilo de Código]]
[[zh:代码指南]]

Development:Coding

2007-03-05T22:22:41Z

Danstowell: /* General rules */

Any collaborative project needs consistency and stability to stay strong.

These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.

==General rules==

# All code files should use the .php extension.
# All template files should use the .html extension.
# All text files should use Unix-style text format (most text editors have this as an option).
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.
# All existing copyright notices must be retained. You can add your own if necessary.
# Each file should include the main config.php file.
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string(). Never delete strings to ensure backwards compatibility of the language packs is maintained.
# All errors should be printed using print_error() to maximise translation and help for users (it automatically links to the docs wiki).
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Development:Output_functions|output functions]].
# User actions should be logged using the [[Development:Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].
# When generating a HTML link, always make it relative to the full site root, i.e. link to '''$CFG->wwwroot/mod/blonk/view.php?id=99''' rather than just '''view.php?id=99'''. This means that your code will work if called by a script in another folder, among other things.

==Coding style==

I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.

1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.

2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)

BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.

define("FORUM_MODE_FLATOLDEST", 1);
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).

function forum_set_display_mode($mode=0) {
global $USER, $CFG;

if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}

5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}

6. Strings should be defined using single quotes where possible, for increased speed.

$var = 'some text without any variables';
$var = "with special characters like a new line \n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.

* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc

8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:

foreach ($objects as $key => $thing) {
process($thing);
}

if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}

9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.

BAD: $b = $a;
GOOD: $b = clone($a);

If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.

==Database structures==

# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[Development:XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.
# '''Never''' make database changes in the STABLE branches. If we did, then users upgrading from one stable version to the next would have duplicate changes occurring, which may cause serious errors.

==Security issues (and handling form and URL data)==

# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from.
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Use data_submitted(), with care. Data must still be cleaned before use.
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
# Any data read from the database must have [[Developer:Slashes|addslashes()]] applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
# Do not use data from $_SERVER if you can avoid it. This has portability issues.
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.

[[Category:Developer]]

[[es:Manual de Estilo de Código]]
[[zh:代码指南]]

Development:Coding

2007-03-05T22:21:51Z

Danstowell: /* General rules */ Note about creating links with $CFG->wwwroot

Any collaborative project needs consistency and stability to stay strong.

These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.

==General rules==

# All code files should use the .php extension.
# All template files should use the .html extension.
# All text files should use Unix-style text format (most text editors have this as an option).
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.
# All existing copyright notices must be retained. You can add your own if necessary.
# Each file should include the main config.php file.
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string(). Never delete strings to ensure backwards compatibility of the language packs is maintained.
# All errors should be printed using print_error() to maximise translation and help for users (it automatically links to the docs wiki).
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Development:Output_functions|output functions]].
# User actions should be logged using the [[Development:Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].
# When generating a HTML link, always make it relative to the full site root, i.e. use $CFG->wwwroot/mod/blonk/view.php?id=99 rather than just view.php?id=99. This means your code will work if called by a script in another folder, among other things.

==Coding style==

I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.

1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.

2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.

GOOD: $quiz
GOOD: $errorstring
GOOD: $assignments (for an array of objects)
GOOD: $i (but only in little loops)

BAD: $Quiz
BAD: $aReallyLongVariableNameWithoutAGoodReason
BAD: $error_string

3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.

define("FORUM_MODE_FLATOLDEST", 1);
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).

function forum_set_display_mode($mode=0) {
global $USER, $CFG;

if ($mode) {
$USER->mode = $mode;
} else if (empty($USER->mode)) {
$USER->mode = $CFG->forum_displaymode;
}
}

5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:

if ($quiz->attempts) {
if ($numattempts > $quiz->attempts) {
error($strtoomanyattempts, "view.php?id=$cm->id");
}
}

6. Strings should be defined using single quotes where possible, for increased speed.

$var = 'some text without any variables';
$var = "with special characters like a new line \n";
$var = 'a very, very long string with a '.$single.' variable in it';
$var = "some $text with $many variables $within it";

7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.

* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.

/**
* The description should be first, with asterisks laid out exactly
* like this example. If you want to refer to a another function,
* do it like this: {@link clean_param()}. Then, add descriptions
* for each parameter as follows.
*
* @param int $postid The PHP type is followed by the variable name
* @param array $scale The PHP type is followed by the variable name
* @param array $ratings The PHP type is followed by the variable name
* @return mixed
*/
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {
if (!$ratings) {
$ratings = array(); // Initialize the empty array
if ($rates = get_records("forum_ratings", "post", $postid)) {
// Process each rating in turn
foreach ($rates as $rate) {
....etc

8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:

foreach ($objects as $key => $thing) {
process($thing);
}

if ($x == $y) {
$a = $b;
} else if ($x == $z) {
$a = $c;
} else {
$a = $d;
}

9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.

BAD: $b = $a;
GOOD: $b = clone($a);

If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.

==Database structures==

# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[Development:XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.
# '''Never''' make database changes in the STABLE branches. If we did, then users upgrading from one stable version to the next would have duplicate changes occurring, which may cause serious errors.

==Security issues (and handling form and URL data)==

# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from.
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.
# Use data_submitted(), with care. Data must still be cleaned before use.
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()
# Any data read from the database must have [[Developer:Slashes|addslashes()]] applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).
# Do not use data from $_SERVER if you can avoid it. This has portability issues.
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.

[[Category:Developer]]

[[es:Manual de Estilo de Código]]
[[zh:代码指南]]

Changing some of the words used

2006-10-22T11:52:46Z

Danstowell: cat

If you have installed Moodle and one to change one or two of the words Moodle uses (for example, if the word "course"/"courses" is not appropriate for your context), simply follow the [[Translation#Making_small_customisations|"Making small customisations"]] instructions in the [[Translation]] instructions. You can define your "localised" strings in a separate file, which means they won't be overwritten when you upgrade Moodle.

[[Category:Language]]
[[Category:Administrator]]

Translation

2006-10-22T11:51:10Z

Danstowell: /* Making small customisations */ bolding

Moodle has been designed for internationalisation. Each 'string' or 'page' of text that is displayed as part of the interface is drawn from a set of language files.

== Structure of a Moodle language pack ==
{{Moodle 1.6}}
*All Moodle language packs may be found in the ''lang'' folder, with each language in a unique folder named the same as the language short name e.g. ''es'', ''nl''. From Moodle 1.6 upwards, the ''lang'' folder may be found in ''moodledata'', with pack names indicating they are UTF-8 language packs e.g. ''es_utf8'', ''nl_utf8''. The default English language pack, ''en_utf8'', remains in ''moodle/lang'', along with a tiny non-UTF-8 version (''en'') for use in the 1.5 to 1.6 upgrade, prior to the database migration process.

*All the main files are in the ''lang/xx_utf8'' folder, with .php extensions (eg ''moodle.php'', ''resource.php'' etc). These files contains short phrases, often called "strings". Each string supports variable substitution, to support variable ordering in different languages.

:e.g. <code>$strdueby = get_string("assignmentdueby", "assignment", userdate($date));</code>

:If a string doesn't exist in a particular language, then the equivalent in English will automatically be used instead.

:There is also a ''help'' folder containing HTML pages for pop-up context-sensitive help.

*Installation language packs may be found in the ''install/lang'' folder. These language packs contain only the strings needed for the installation process. The files are generated automatically every night by the download.moodle.org server and '''must not be changed manually'''. For translators this is a unusual experience, since changes you add to the strings used in the installation script will not be visible until 24 hours later in a new download of your 1.6 installation.

==Creating a new language pack==

If your language is not yet supported by Moodle, you may want to start a new translation. If you are starting a new language, please contact [[User:koen roggemans|Koen Roggemans]] our Translation Coordinator (''translation@moodle.org''). You may also like to post in the Using Moodle [http://moodle.org/mod/forum/view.php?id=43 Languages Forum].

All you need to do is create a new folder in the lang directory using the 2-letter code for your language. You can find these standard codes in ''lib/languages.php''. If you are making a local variation of another language, use the code of that language with an underscore and a meaningful two letter extension (e.g. pt for Portuguese and pt_br for Brasilian variation of the Portuguese language pack). If you are making a Unicode version add _utf8 at the end (eg sr_utf8). Language packs created with a new Moodle 1.6 or with a Moodle 1.6 in Unicode mode are always in Unicode and should get the _utf8 suffix.

Next, copy the ''langconfig.php'' from another language into your new directory. The one from the "en_utf8" folder is usually best.

You are now ready to start inserting new strings by editing your language... see below for details on this.

Note that your new language pack may not show up immediately on the dropdown list if under your site configuration you have langcache set to "Yes."

{{Moodle 1.6}}
Since Moodle 1.6, only UTF-8 is used as characterset. This setting is located in a string named "thischarset" in ''langconfig.php'' and should not be changed. All other settings for your language pack, as the notation of dates, the locale string, the direction etc. are in this file and can be changed there. Just be careful! ;-)

==Editing an existing language pack==

===Making small customisations===

If you just want to change a few things in the interface to suit your own site better, don't start editing one of the standard language packs. If you do then your changes will be overwritten next time you upgrade to a new Moodle.

Instead, use the instructions above for making a brand new language pack, add a string 'parentlanguage' (in '''''langconfig.php''''') with the code of the language that is most similar to yours. That language will be checked by Moodle for anything missing from yours. Here's an example of such a line:

$string['parentlanguage'] = 'en_utf8';

A good name for a local English variant could be "en_utf8_local", and the parent language would be defined as "en_utf8" or "en_us_utf8". ''(For Moodle 1.5 and earlier, omit the "_utf8" from the names, since older versions of Moodle don't use UTF8.)''

Note that you also have to create a string 'thislanguage' in '''''moodle.php''''' for your "en_utf8_local" language pack:

$string['thislanguage'] = 'English at OCU';

In Moodle 1.5.x and earlier you would have to then make sure everyone chooses your new language pack. They can change it in their profiles or you can issue an SQL command to change everyone, and prevent them changing it by restricting the available languages on Administration >> Configuration >> [[Variables]].

{{Moodle 1.6}}
Starting in Moodle 1.6, the very best method is just to create a new language directory called "xxxx_local" where xxxx is the name of the language pack you want to modify (eg es_utf8_local or ja_utf8_local). This new local language pack will automatically be checked before the main one. The local pack only needs to contain the local changes (you don't need a complete copy of the language you are modifying). It will not appear in the language menus for selection and your users do not need to change their settings.

The 'parentlanguage' method described above for 1.5 still works, just in case you want to create more than one variant of one language. In this case, you still have to add the 'thislanguage' string, except in 1.6 you add it to the ''langconfig.php'' and not to ''moodle.php''.

===Translating the Moodle interface language files (the "string" files)===

# Log on to your Moodle server as an administrator.
# Go to Administration >> Configuration >> [[Language]], which is the language administration page.
# On this page you can choose your language from the menu, then choose "Compare and Edit Language".
# You should see forms you can edit for each file. If you do not, then you may have to make sure that the files are writeable - you may have to change file permissions in your web folder.
# The forms consist of three columns, the first is the name of each string, the second is that string in English, and the last is translation in the current language.
# Edit missing strings in each files (highlighted in colour), remembering to hit the "Save changes" button at the end of each form.
# It's OK to leave strings empty - Moodle will simply use the parent language for that string instead. You can define the parent language in langconfig.php, otherwise English is always used by default.
# A quick way to see all the missing strings is by using the button to "Check for missing strings". Leave the untranslated strings completely empty or this handy tool won't work.

===Translating the help files===

There is a built-in editor in Moodle to translate the help files. It uses the en_utf8 language pack as a reference language. You are strongly advised to use this editor: it cleans out some possible problems, it warns you for old translations and it marks (with stars in the drop down list) wich files are out of date and takes care of Unicode.
If you want another language than English as a reference (wich is not a good idea), you copy a help file from the reference language pack and paste it on the same location in your own language pack. Then use a plain text editor with Unicode support to translate the file, making sure not to modify any code in the file (there usually is no code, just HTML-tags). (DON'T USE A WORDPROCESSOR to write the help-files because these programs add too much rubbish to the files).
Don't leave untranslated help files or empty files in your language pack.

Take care to write the helpfiles XHTML-compliant. This means in short:

* All tags should be closed: <pre><p>lalala</p></pre>
* All elements should be nested: <pre><p> lalala <em>lalala</em> </p></pre>
* All elements and attributes must be lower case
* All atributes should be written in full and with quotes : <pre><p align="right"> lalala </p></pre>
* Empty elements must end with />: <pre><br /> <hr /></pre>. You should add an extra space before the "/" symbol.
* An <img should have an alt="" (it can be empty) en must be closed like other empty elements with a space and /> like <pre><img alt="" src="picture.gif" /></pre>
* <?= and <? should be <pre><?php</pre>
* There should not be ANY font tags at all. <pre><p><em> <h1> <h2></pre> etc should be enough for the language files ...

None of the files in the help folder need a doc type, html, body, head opening and closing tags - these files are included with ''help.php''. The script will take care of welforming the pages. This means also there is not much room for HTML creativity! Please stick to the English example.
{{Moodle 1.6}}
The files in the docs folder must be completely XHTML compliant, including doc type, header etc. From Moodle 1.6 they will be moved to this wiki.

Clicking on "Check for missing strings" in the language administration screen will also show you what files you are missing. If you have missing files then Moodle will use the parent language instead, so don't leave copies of untranslated help files in your language pack or this handy tool won't work.

==Submitting your language pack to the Moodle project==

Sharing your translation with Moodle will ensure that you help other people who speak your language. Your interface language will be available in future versions of Moodle.

Simply archive your whole new language directory as a zip file and email it to ''translation@moodle.org''.

We will get back to you with further details.

Checklist you can use before committing:

* No empty files?
* No untranslated files or strings?
* Help files not edited with a wordprocessor?
* README file contains language, name and emailadress of the translator?
* Foldername is the right language code (check ''moodle\lib\languages.php'')?
* Does the language pack run errorfree on a testsite?
* Are the strings and files XHTML compliant?
* Does ''langconfig.php'' exists and is it correct?

==Maintenance of a standard language pack==

If you are committed to maintaining a language in Moodle, it's best to use [[CVS for Developers|Moodle CVS]] so that you have an up-to-date version of Moodle, and can easily "check in" your changes directly into the Moodle project.
{{Moodle 1.6}}
You should always use HEAD to do translation. Instead of modifying the lang pack within your main code tree as it was until Moodle 1.6, you will now be modifying the one within your dataroot/lang directory.

* Always check out the very latest Moodle code
* Upgrade your site. Of course you use a NON-PRODUCTION server for this.
* Go to your dataroot directory and check out the new lang directory from CVS there like this on Unix/Linux

cd moodledata (for example)
cvs -z3 -d:ext:me@moodle.cvs.sourceforge.net:/cvsroot/moodle co lang

or like this with Tortoise on Windows,

right click on your dataroot folder, choose "CVS Checkout",
CVSROOT field: :ext:sfusername@moodle.cvs.sourceforge.net:/cvsroot/moodle
Module: lang

* Continue editing languages from within the Moodle GUI as you did before Moodle 1.6.

To check them into CVS, just go into the dataroot/lang directory and commit your changes.

If you really want to continue updating the language packs for 1.5.x or earlier, then you should zip the folder of your langpack and mail it to ''translation@moodle.org''. CVS write access on moodle/lang/xx will be moved to lang/xx_utf8.

Please contact ''translation@moodle.org'' if you need help setting this up.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=43 Languages Forum] - news and discussion about issues that affect translations
*[[Translation credits]]
*To keep in touch with changes in the project on a day-to-day basis it is recommended that you subscribe to the [http://sourceforge.net/mail/?group_id=30935 CVS mailing list]. This helps to keep your translation as close to the English text as possible.

[[Category:Developer]]
[[Category:Language]]

[[es:Traducciones]]
[[fr:Traduction]]
[[nl:Vertalen]]

Translation

2006-10-22T11:43:01Z

Danstowell: /* Making small customisations */ Updating information so it's more oriented towards 1.6 and later, also reworked it slightly

Moodle has been designed for internationalisation. Each 'string' or 'page' of text that is displayed as part of the interface is drawn from a set of language files.

== Structure of a Moodle language pack ==
{{Moodle 1.6}}
*All Moodle language packs may be found in the ''lang'' folder, with each language in a unique folder named the same as the language short name e.g. ''es'', ''nl''. From Moodle 1.6 upwards, the ''lang'' folder may be found in ''moodledata'', with pack names indicating they are UTF-8 language packs e.g. ''es_utf8'', ''nl_utf8''. The default English language pack, ''en_utf8'', remains in ''moodle/lang'', along with a tiny non-UTF-8 version (''en'') for use in the 1.5 to 1.6 upgrade, prior to the database migration process.

*All the main files are in the ''lang/xx_utf8'' folder, with .php extensions (eg ''moodle.php'', ''resource.php'' etc). These files contains short phrases, often called "strings". Each string supports variable substitution, to support variable ordering in different languages.

:e.g. <code>$strdueby = get_string("assignmentdueby", "assignment", userdate($date));</code>

:If a string doesn't exist in a particular language, then the equivalent in English will automatically be used instead.

:There is also a ''help'' folder containing HTML pages for pop-up context-sensitive help.

*Installation language packs may be found in the ''install/lang'' folder. These language packs contain only the strings needed for the installation process. The files are generated automatically every night by the download.moodle.org server and '''must not be changed manually'''. For translators this is a unusual experience, since changes you add to the strings used in the installation script will not be visible until 24 hours later in a new download of your 1.6 installation.

==Creating a new language pack==

If your language is not yet supported by Moodle, you may want to start a new translation. If you are starting a new language, please contact [[User:koen roggemans|Koen Roggemans]] our Translation Coordinator (''translation@moodle.org''). You may also like to post in the Using Moodle [http://moodle.org/mod/forum/view.php?id=43 Languages Forum].

All you need to do is create a new folder in the lang directory using the 2-letter code for your language. You can find these standard codes in ''lib/languages.php''. If you are making a local variation of another language, use the code of that language with an underscore and a meaningful two letter extension (e.g. pt for Portuguese and pt_br for Brasilian variation of the Portuguese language pack). If you are making a Unicode version add _utf8 at the end (eg sr_utf8). Language packs created with a new Moodle 1.6 or with a Moodle 1.6 in Unicode mode are always in Unicode and should get the _utf8 suffix.

Next, copy the ''langconfig.php'' from another language into your new directory. The one from the "en_utf8" folder is usually best.

You are now ready to start inserting new strings by editing your language... see below for details on this.

Note that your new language pack may not show up immediately on the dropdown list if under your site configuration you have langcache set to "Yes."

{{Moodle 1.6}}
Since Moodle 1.6, only UTF-8 is used as characterset. This setting is located in a string named "thischarset" in ''langconfig.php'' and should not be changed. All other settings for your language pack, as the notation of dates, the locale string, the direction etc. are in this file and can be changed there. Just be careful! ;-)

==Editing an existing language pack==

===Making small customisations===

If you just want to change a few things in the interface to suit your own site better, don't start editing one of the standard language packs. If you do then your changes will be overwritten next time you upgrade to a new Moodle.

Instead, use the instructions above for making a brand new language pack, add a string 'parentlanguage' (in ''langconfig.php'') with the code of the language that is most similar to yours. That language will be checked by Moodle for anything missing from yours. Here's an example of such a line:

$string['parentlanguage'] = 'en_utf8';

A good name for a local English variant could be "en_utf8_local", and the parent language would be defined as "en_utf8" or "en_us_utf8". ''(For Moodle 1.5 and earlier, omit the "_utf8" from the names, since older versions of Moodle don't use UTF8.)''

Note that you also have to create a string 'thislanguage' in ''moodle.php'' for your "en_utf8_local" language pack:

$string['thislanguage'] = 'English at OCU';

In Moodle 1.5.x and earlier you would have to then make sure everyone chooses your new language pack. They can change it in their profiles or you can issue an SQL command to change everyone, and prevent them changing it by restricting the available languages on Administration >> Configuration >> [[Variables]].

{{Moodle 1.6}}
Starting in Moodle 1.6, the very best method is just to create a new language directory called "xxxx_local" where xxxx is the name of the language pack you want to modify (eg es_utf8_local or ja_utf8_local). This new local language pack will automatically be checked before the main one. The local pack only needs to contain the local changes (you don't need a complete copy of the language you are modifying). It will not appear in the language menus for selection and your users do not need to change their settings.

The 'parentlanguage' method described above for 1.5 still works, just in case you want to create more than one variant of one language. In this case, you still have to add the 'thislanguage' string, except in 1.6 you add it to the ''langconfig.php'' and not to ''moodle.php''.

===Translating the Moodle interface language files (the "string" files)===

# Log on to your Moodle server as an administrator.
# Go to Administration >> Configuration >> [[Language]], which is the language administration page.
# On this page you can choose your language from the menu, then choose "Compare and Edit Language".
# You should see forms you can edit for each file. If you do not, then you may have to make sure that the files are writeable - you may have to change file permissions in your web folder.
# The forms consist of three columns, the first is the name of each string, the second is that string in English, and the last is translation in the current language.
# Edit missing strings in each files (highlighted in colour), remembering to hit the "Save changes" button at the end of each form.
# It's OK to leave strings empty - Moodle will simply use the parent language for that string instead. You can define the parent language in langconfig.php, otherwise English is always used by default.
# A quick way to see all the missing strings is by using the button to "Check for missing strings". Leave the untranslated strings completely empty or this handy tool won't work.

===Translating the help files===

There is a built-in editor in Moodle to translate the help files. It uses the en_utf8 language pack as a reference language. You are strongly advised to use this editor: it cleans out some possible problems, it warns you for old translations and it marks (with stars in the drop down list) wich files are out of date and takes care of Unicode.
If you want another language than English as a reference (wich is not a good idea), you copy a help file from the reference language pack and paste it on the same location in your own language pack. Then use a plain text editor with Unicode support to translate the file, making sure not to modify any code in the file (there usually is no code, just HTML-tags). (DON'T USE A WORDPROCESSOR to write the help-files because these programs add too much rubbish to the files).
Don't leave untranslated help files or empty files in your language pack.

Take care to write the helpfiles XHTML-compliant. This means in short:

* All tags should be closed: <pre><p>lalala</p></pre>
* All elements should be nested: <pre><p> lalala <em>lalala</em> </p></pre>
* All elements and attributes must be lower case
* All atributes should be written in full and with quotes : <pre><p align="right"> lalala </p></pre>
* Empty elements must end with />: <pre><br /> <hr /></pre>. You should add an extra space before the "/" symbol.
* An <img should have an alt="" (it can be empty) en must be closed like other empty elements with a space and /> like <pre><img alt="" src="picture.gif" /></pre>
* <?= and <? should be <pre><?php</pre>
* There should not be ANY font tags at all. <pre><p><em> <h1> <h2></pre> etc should be enough for the language files ...

None of the files in the help folder need a doc type, html, body, head opening and closing tags - these files are included with ''help.php''. The script will take care of welforming the pages. This means also there is not much room for HTML creativity! Please stick to the English example.
{{Moodle 1.6}}
The files in the docs folder must be completely XHTML compliant, including doc type, header etc. From Moodle 1.6 they will be moved to this wiki.

Clicking on "Check for missing strings" in the language administration screen will also show you what files you are missing. If you have missing files then Moodle will use the parent language instead, so don't leave copies of untranslated help files in your language pack or this handy tool won't work.

==Submitting your language pack to the Moodle project==

Sharing your translation with Moodle will ensure that you help other people who speak your language. Your interface language will be available in future versions of Moodle.

Simply archive your whole new language directory as a zip file and email it to ''translation@moodle.org''.

We will get back to you with further details.

Checklist you can use before committing:

* No empty files?
* No untranslated files or strings?
* Help files not edited with a wordprocessor?
* README file contains language, name and emailadress of the translator?
* Foldername is the right language code (check ''moodle\lib\languages.php'')?
* Does the language pack run errorfree on a testsite?
* Are the strings and files XHTML compliant?
* Does ''langconfig.php'' exists and is it correct?

==Maintenance of a standard language pack==

If you are committed to maintaining a language in Moodle, it's best to use [[CVS for Developers|Moodle CVS]] so that you have an up-to-date version of Moodle, and can easily "check in" your changes directly into the Moodle project.
{{Moodle 1.6}}
You should always use HEAD to do translation. Instead of modifying the lang pack within your main code tree as it was until Moodle 1.6, you will now be modifying the one within your dataroot/lang directory.

* Always check out the very latest Moodle code
* Upgrade your site. Of course you use a NON-PRODUCTION server for this.
* Go to your dataroot directory and check out the new lang directory from CVS there like this on Unix/Linux

cd moodledata (for example)
cvs -z3 -d:ext:me@moodle.cvs.sourceforge.net:/cvsroot/moodle co lang

or like this with Tortoise on Windows,

right click on your dataroot folder, choose "CVS Checkout",
CVSROOT field: :ext:sfusername@moodle.cvs.sourceforge.net:/cvsroot/moodle
Module: lang

* Continue editing languages from within the Moodle GUI as you did before Moodle 1.6.

To check them into CVS, just go into the dataroot/lang directory and commit your changes.

If you really want to continue updating the language packs for 1.5.x or earlier, then you should zip the folder of your langpack and mail it to ''translation@moodle.org''. CVS write access on moodle/lang/xx will be moved to lang/xx_utf8.

Please contact ''translation@moodle.org'' if you need help setting this up.

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=43 Languages Forum] - news and discussion about issues that affect translations
*[[Translation credits]]
*To keep in touch with changes in the project on a day-to-day basis it is recommended that you subscribe to the [http://sourceforge.net/mail/?group_id=30935 CVS mailing list]. This helps to keep your translation as close to the English text as possible.

[[Category:Developer]]
[[Category:Language]]

[[es:Traducciones]]
[[fr:Traduction]]
[[nl:Vertalen]]

Changing some of the words used

2006-10-22T11:31:35Z

Danstowell: I think it's worth having this page since the instructions are otherwise "buried" in the Translation page. It took me ages to find the instructions just now!

Development:Database fields

2006-08-23T12:38:27Z

Danstowell:

2006-08-06T13:04:11Z

Danstowell:

#REDIRECT [[Speech tools]]

Audioconferencing

2006-08-06T13:03:47Z

Danstowell:

#REDIRECT [[Speech tools]]