Skip to content

GitLab

Commit ec69f0ec authored by jhodgdon's avatar jhodgdon
Browse files

Issue #1431632 by NROTC_Webmaster: Fix up API docs for translation module

parent 8aa81cac
Hide whitespace changes
Inline Side-by-side
core/modules/translation/translation.module
View file @ ec69f0ec
......@@ -2,21 +2,21 @@
/**
* @file
* Manages content translations.
* Manages content translations.
*
* Translations are managed in sets of posts, which represent the same
* information in different languages. Only content types for which the
* administrator explicitly enabled translations could have translations
* associated. Translations are managed in sets with exactly one source
* post per set. The source post is used to translate to different
* languages, so if the source post is significantly updated, the
* editor can decide to mark all translations outdated.
* Translations are managed in sets of posts, which represent the same
* information in different languages. Only content types for which the
* administrator has explicitly enabled translations could have translations
* associated. Translations are managed in sets with exactly one source post
* per set. The source post is used to translate to different languages, so if
* the source post is significantly updated, the editor can decide to mark all
* translations outdated.
*
* The node table stores the values used by this module:
* - 'tnid' is the translation set id, which equals the node id
* of the source post.
* - 'translate' is a flag, either indicating that the translation
* is up to date (0) or needs to be updated (1).
* The node table stores the values used by this module:
* - tnid: Integer for the translation set ID, which equals the node ID of the
* source post.
* - translate: Integer flag, either indicating that the translation is up to
* date (0) or needs to be updated (1).
*/
/**
......@@ -70,11 +70,18 @@ function translation_menu() {
}
/**
* Menu access callback.
* Access callback: Checks that the user has permission to 'translate content'.
*
* Only display translation tab for node types, which have translation enabled
* and where the current node is not language neutral (which should span
* all languages).
* Only displays the translation tab for nodes that are not language-neutral
* of types that have translation enabled.
*
* @param $node
* A node object.
*
* @return
* TRUE if the translation tab should be displayed, FALSE otherwise.
*
* @see translation_menu()
*/
function _translation_tab_access($node) {
if ($node->langcode != LANGUAGE_NOT_SPECIFIED && translation_supported_type($node->type) && node_access('view', $node)) {
......@@ -107,7 +114,7 @@ function translation_permission() {
}
/**
* Implements hook_form_FORM_ID_alter().
* Implements hook_form_FORM_ID_alter() for node_type_form().
*/
function translation_form_node_type_form_alter(&$form, &$form_state) {
// Add translation option to content type form.
......@@ -118,10 +125,12 @@ function translation_form_node_type_form_alter(&$form, &$form_state) {
}
/**
* Implements hook_form_BASE_FORM_ID_alter().
* Implements hook_form_BASE_FORM_ID_alter() for node_form().
*
* This function alters language fields on node edit forms when a translation is
* about to be created.
* Alters language fields on node edit forms when a translation is about to be
* created.
*
* @see node_form()
*/
function translation_form_node_form_alter(&$form, &$form_state) {
if (translation_supported_type($form['#node']->type)) {
......@@ -206,9 +215,9 @@ function translation_form_node_form_alter(&$form, &$form_state) {
/**
* Implements hook_node_view().
*
* Display translation links with language names, if this node is part of
* a translation set. If no language provider is enabled "fall back" to the
* simple links built through the result of translation_node_get_translations().
* Displays translation links with language names if this node is part of a
* translation set. If no language provider is enabled, "fall back" to simple
* links built through the result of translation_node_get_translations().
*/
function translation_node_view($node, $view_mode) {
// If the site has no translations or is not multilingual we have no content
......@@ -378,7 +387,7 @@ function translation_node_update($node) {
/**
* Implements hook_node_validate().
*
* Ensure that duplicate translations can not be created for the same source.
* Ensures that duplicate translations can't be created for the same source.
*/
function translation_node_validate($node, $form) {
// Only act on translatable nodes with a tnid or translation_source.
......@@ -402,8 +411,10 @@ function translation_node_predelete($node) {
}
/**
* Remove a node from its translation set (if any)
* and update the set accordingly.
* Removes a node from its translation set and updates accordingly.
*
* @param $node
* A node object.
*/
function translation_remove_from_set($node) {
if (isset($node->tnid)) {
......@@ -437,17 +448,18 @@ function translation_remove_from_set($node) {
}
/**
* Get all nodes in a translation set, represented by $tnid.
* Gets all nodes in a given translation set.
*
* @param $tnid
* The translation source nid of the translation set, the identifier
* of the node used to derive all translations in the set.
* The translation source nid of the translation set, the identifier of the
* node used to derive all translations in the set.
*
* @return
* Array of partial node objects (nid, title, langcode) representing
* all nodes in the translation set, in effect all translations
* of node $tnid, including node $tnid itself. Because these are
* partial nodes, you need to node_load() the full node, if you
* need more properties. The array is indexed by language code.
* Array of partial node objects (nid, title, langcode) representing all
* nodes in the translation set, in effect all translations of node $tnid,
* including node $tnid itself. Because these are partial nodes, you need to
* node_load() the full node, if you need more properties. The array is
* indexed by language code.
*/
function translation_node_get_translations($tnid) {
if (is_numeric($tnid) && $tnid) {
......@@ -473,21 +485,21 @@ function translation_node_get_translations($tnid) {
* Returns whether the given content type has support for translations.
*
* @return
* Boolean value.
* TRUE if translation is supported, and FALSE if not.
*/
function translation_supported_type($type) {
return variable_get('node_type_language_' . $type, 0) == TRANSLATION_ENABLED;
}
/**
* Return paths of all translations of a node, based on
* its Drupal path.
* Returns the paths of all translations of a node, based on its Drupal path.
*
* @param $path
* A Drupal path, for example node/432.
*
* @return
* An array of paths of translations of the node accessible
* to the current user keyed with language codes.
* An array of paths of translations of the node accessible to the current
* user, keyed with language codes.
*/
function translation_path_get_translations($path) {
$paths = array();
......
core/modules/translation/translation.pages.inc
View file @ ec69f0ec
......@@ -2,14 +2,19 @@
/**
* @file
* User page callbacks for the translation module.
* User page callbacks for the Translation module.
*/
/**
* Overview page for a node's translations.
* Page callback: Displays a list of a node's translations.
*
* @param $node
* Node object.
* A node object.
*
* @return
* A render array for a page containing a list of content.
*
* @see translation_menu()
*/
function translation_node_overview($node) {
include_once DRUPAL_ROOT . '/core/includes/language.inc';
......
core/modules/translation/translation.test
View file @ ec69f0ec
......@@ -2,9 +2,12 @@
/**
* @file
* Tests for translation.module
* Tests for the Translation module.
*/
/**
* Functional tests for the Translation module.
*/
class TranslationTestCase extends DrupalWebTestCase {
protected $book;
......@@ -54,8 +57,7 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Create a basic page with translation, modify the basic page outdating
* translation, and update translation.
* Creates, modifies, and updates a basic page with a translation.
*/
function testContentTranslation() {
// Create Basic page in English.
......@@ -147,7 +149,7 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Check that language switch links behave properly.
* Checks that the language switch links behave properly.
*/
function testLanguageSwitchLinks() {
// Create a Basic page in English and its translations in Spanish and
......@@ -188,7 +190,7 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Test that the language switcher block alterations work as intended.
* Tests that the language switcher block alterations work as intended.
*/
function testLanguageSwitcherBlockIntegration() {
// Enable Italian to have three items in the language switcher block.
......@@ -251,7 +253,7 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Reset static caches to make the test code match the client site behavior.
* Resets static caches to make the test code match the client-side behavior.
*/
function resetCaches() {
drupal_static_reset('language_list');
......@@ -260,15 +262,20 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Return an empty node data structure.
* Returns an empty node data structure.
*
* @param $langcode
* The language code.
*
* @return
* An empty node data structure.
*/
function emptyNode($langcode) {
return (object) array('nid' => NULL, 'langcode' => $langcode);
}
/**
* Install a the specified language if it has not been already. Otherwise make sure that
* the language is enabled.
* Installs the specified language, or enables it if it is already installed.
*
* @param $language_code
* The language code the check.
......@@ -305,14 +312,17 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Create a "Basic page" in the specified language.
* Creates a "Basic page" in the specified language.
*
* @param $title
* Title of basic page in specified language.
* The title of a basic page in the specified language.
* @param $body
* Body of basic page in specified language.
* The body of a basic page in the specified language.
* @param $langcode
* (optional) Language code.
*
* @return
* A node object.
*/
function createPage($title, $body, $langcode = NULL) {
$edit = array();
......@@ -333,17 +343,19 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Create a translation for the specified basic page in the specified
* language.
* Creates a translation for a basic page in the specified language.
*
* @param $node
* The basic page to create translation for.
* The basic page to create the translation for.
* @param $title
* Title of basic page in specified language.
* The title of a basic page in the specified language.
* @param $body
* Body of basic page in specified language.
* The body of a basic page in the specified language.
* @param $langcode
* Language code.
* (optional) Language code.
*
* @return
* Translation object.
*/
function createTranslation($node, $title, $body, $langcode) {
$this->drupalGet('node/add/page', array('query' => array('translation' => $node->nid, 'target' => $langcode)));
......@@ -368,10 +380,10 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Assert that an element identified by the given XPath has the given content.
* Asserts an element identified by the given XPath has the given content.
*
* @param $xpath
* XPath used to find the element.
* The XPath used to find the element.
* @param array $arguments
* An array of arguments with keys in the form ':name' matching the
* placeholders in the query. The values may be either strings or numeric
......@@ -379,7 +391,7 @@ class TranslationTestCase extends DrupalWebTestCase {
* @param $value
* The text content of the matched element to assert.
* @param $message
* Message to display.
* The message to display.
* @param $group
* The group this message belongs to.
*
......@@ -392,7 +404,7 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Check that the specified language switch links are found/not found.
* Tests whether the specified language switch links are found.
*
* @param $node
* The node to display.
......@@ -404,7 +416,7 @@ class TranslationTestCase extends DrupalWebTestCase {
* The page areas to be checked.
*
* @return
* TRUE if the language switch links are found/not found.
* TRUE if the language switch links are found, FALSE if not.
*/
function assertLanguageSwitchLinks($node, $translation, $find = TRUE, $types = NULL) {
if (empty($types)) {
......@@ -446,7 +458,19 @@ class TranslationTestCase extends DrupalWebTestCase {
}
/**
* Search for elements matching the given xpath and value.
* Searches for elements matching the given xpath and value.
*
* @param $xpath
* The XPath used to find the element.
* @param array $arguments
* An array of arguments with keys in the form ':name' matching the
* placeholders in the query. The values may be either strings or numeric
* values.
* @param $value
* The text content of the matched element to assert.
*
* @return
* TRUE if found, otherwise FALSE.
*/
function findContentByXPath($xpath, array $arguments = array(), $value = NULL) {
$elements = $this->xpath($xpath, $arguments);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment