Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

8.0.x
Jennifer Hodgdon 2012-03-12 09:02:53 -07:00
parent 8aa81cac8c
commit ec69f0ec92
3 changed files with 108 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
core/modules/translation/translation.module
View File

@ -2,21 +2,21 @@
/** /**
* @file * @file
* Manages content translations. * Manages content translations.
* *
* Translations are managed in sets of posts, which represent the same * Translations are managed in sets of posts, which represent the same
* information in different languages. Only content types for which the * information in different languages. Only content types for which the
* administrator explicitly enabled translations could have translations * administrator has explicitly enabled translations could have translations
* associated. Translations are managed in sets with exactly one source * associated. Translations are managed in sets with exactly one source post
* post per set. The source post is used to translate to different * per set. The source post is used to translate to different languages, so if
* languages, so if the source post is significantly updated, the * the source post is significantly updated, the editor can decide to mark all
* editor can decide to mark all translations outdated. * translations outdated.
* *
* The node table stores the values used by this module: * The node table stores the values used by this module:
* - 'tnid' is the translation set id, which equals the node id * - tnid: Integer for the translation set ID, which equals the node ID of the
* of the source post. * source post.
* - 'translate' is a flag, either indicating that the translation * - translate: Integer flag, either indicating that the translation is up to
* is up to date (0) or needs to be updated (1). * 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 * Only displays the translation tab for nodes that are not language-neutral
* and where the current node is not language neutral (which should span * of types that have translation enabled.
* all languages). *
* @param $node
* A node object.
*
* @return
* TRUE if the translation tab should be displayed, FALSE otherwise.
*
* @see translation_menu()
*/ */
function _translation_tab_access($node) { function _translation_tab_access($node) {
if ($node->langcode != LANGUAGE_NOT_SPECIFIED && translation_supported_type($node->type) && node_access('view', $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) { function translation_form_node_type_form_alter(&$form, &$form_state) {
// Add translation option to content type form. // 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 * Alters language fields on node edit forms when a translation is about to be
* about to be created. * created.
*
* @see node_form()
*/ */
function translation_form_node_form_alter(&$form, &$form_state) { function translation_form_node_form_alter(&$form, &$form_state) {
if (translation_supported_type($form['#node']->type)) { if (translation_supported_type($form['#node']->type)) {
@ -206,9 +215,9 @@ function translation_form_node_form_alter(&$form, &$form_state) {
/** /**
* Implements hook_node_view(). * Implements hook_node_view().
* *
* Display translation links with language names, if this node is part of * Displays translation links with language names if this node is part of a
* a translation set. If no language provider is enabled "fall back" to the * translation set. If no language provider is enabled, "fall back" to simple
* simple links built through the result of translation_node_get_translations(). * links built through the result of translation_node_get_translations().
*/ */
function translation_node_view($node, $view_mode) { function translation_node_view($node, $view_mode) {
// If the site has no translations or is not multilingual we have no content // 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(). * 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) { function translation_node_validate($node, $form) {
// Only act on translatable nodes with a tnid or translation_source. // 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) * Removes a node from its translation set and updates accordingly.
* and update the set accordingly. *
* @param $node
* A node object.
*/ */
function translation_remove_from_set($node) { function translation_remove_from_set($node) {
if (isset($node->tnid)) { 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 * @param $tnid
* The translation source nid of the translation set, the identifier * The translation source nid of the translation set, the identifier of the
* of the node used to derive all translations in the set. * node used to derive all translations in the set.
*
* @return * @return
* Array of partial node objects (nid, title, langcode) representing * Array of partial node objects (nid, title, langcode) representing all
* all nodes in the translation set, in effect all translations * nodes in the translation set, in effect all translations of node $tnid,
* of node $tnid, including node $tnid itself. Because these are * including node $tnid itself. Because these are partial nodes, you need to
* partial nodes, you need to node_load() the full node, if you * node_load() the full node, if you need more properties. The array is
* need more properties. The array is indexed by language code. * indexed by language code.
*/ */
function translation_node_get_translations($tnid) { function translation_node_get_translations($tnid) {
if (is_numeric($tnid) && $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. * Returns whether the given content type has support for translations.
* *
* @return * @return
* Boolean value. * TRUE if translation is supported, and FALSE if not.
*/ */
function translation_supported_type($type) { function translation_supported_type($type) {
return variable_get('node_type_language_' . $type, 0) == TRANSLATION_ENABLED; return variable_get('node_type_language_' . $type, 0) == TRANSLATION_ENABLED;
} }
/** /**
* Return paths of all translations of a node, based on * Returns the paths of all translations of a node, based on its Drupal path.
* its Drupal path.
* *
* @param $path * @param $path
* A Drupal path, for example node/432. * A Drupal path, for example node/432.
*
* @return * @return
* An array of paths of translations of the node accessible * An array of paths of translations of the node accessible to the current
* to the current user keyed with language codes. * user, keyed with language codes.
*/ */
function translation_path_get_translations($path) { function translation_path_get_translations($path) {
$paths = array(); $paths = array();

11
core/modules/translation/translation.pages.inc
View File

@ -2,14 +2,19 @@
/** /**
* @file * @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 * @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) { function translation_node_overview($node) {
include_once DRUPAL_ROOT . '/core/includes/language.inc'; include_once DRUPAL_ROOT . '/core/includes/language.inc';

72
core/modules/translation/translation.test
View File

@ -2,9 +2,12 @@
/** /**
* @file * @file
* Tests for translation.module * Tests for the Translation module.
*/ */
/**
* Functional tests for the Translation module.
*/
class TranslationTestCase extends DrupalWebTestCase { class TranslationTestCase extends DrupalWebTestCase {
protected $book; protected $book;
@ -54,8 +57,7 @@ class TranslationTestCase extends DrupalWebTestCase {
} }
/** /**
* Create a basic page with translation, modify the basic page outdating * Creates, modifies, and updates a basic page with a translation.
* translation, and update translation.
*/ */
function testContentTranslation() { function testContentTranslation() {
// Create Basic page in English. // 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() { function testLanguageSwitchLinks() {
// Create a Basic page in English and its translations in Spanish and // 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() { function testLanguageSwitcherBlockIntegration() {
// Enable Italian to have three items in the language switcher block. // 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() { function resetCaches() {
drupal_static_reset('language_list'); 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) { function emptyNode($langcode) {
return (object) array('nid' => NULL, 'langcode' => $langcode); return (object) array('nid' => NULL, 'langcode' => $langcode);
} }
/** /**
* Install a the specified language if it has not been already. Otherwise make sure that * Installs the specified language, or enables it if it is already installed.
* the language is enabled.
* *
* @param $language_code * @param $language_code
* The language code the check. * 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 * @param $title
* Title of basic page in specified language. * The title of a basic page in the specified language.
* @param $body * @param $body
* Body of basic page in specified language. * The body of a basic page in the specified language.
* @param $langcode * @param $langcode
* (optional) Language code. * (optional) Language code.
*
* @return
* A node object.
*/ */
function createPage($title, $body, $langcode = NULL) { function createPage($title, $body, $langcode = NULL) {
$edit = array(); $edit = array();
@ -333,17 +343,19 @@ class TranslationTestCase extends DrupalWebTestCase {
} }
/** /**
* Create a translation for the specified basic page in the specified * Creates a translation for a basic page in the specified language.
* language.
* *
* @param $node * @param $node
* The basic page to create translation for. * The basic page to create the translation for.
* @param $title * @param $title
* Title of basic page in specified language. * The title of a basic page in the specified language.
* @param $body * @param $body
* Body of basic page in specified language. * The body of a basic page in the specified language.
* @param $langcode * @param $langcode
* Language code. * (optional) Language code.
*
* @return
* Translation object.
*/ */
function createTranslation($node, $title, $body, $langcode) { function createTranslation($node, $title, $body, $langcode) {
$this->drupalGet('node/add/page', array('query' => array('translation' => $node->nid, 'target' => $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 * @param $xpath
* XPath used to find the element. * The XPath used to find the element.
* @param array $arguments * @param array $arguments
* An array of arguments with keys in the form ':name' matching the * An array of arguments with keys in the form ':name' matching the
* placeholders in the query. The values may be either strings or numeric * placeholders in the query. The values may be either strings or numeric
@ -379,7 +391,7 @@ class TranslationTestCase extends DrupalWebTestCase {
* @param $value * @param $value
* The text content of the matched element to assert. * The text content of the matched element to assert.
* @param $message * @param $message
* Message to display. * The message to display.
* @param $group * @param $group
* The group this message belongs to. * 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 * @param $node
* The node to display. * The node to display.
@ -404,7 +416,7 @@ class TranslationTestCase extends DrupalWebTestCase {
* The page areas to be checked. * The page areas to be checked.
* *
* @return * @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) { function assertLanguageSwitchLinks($node, $translation, $find = TRUE, $types = NULL) {
if (empty($types)) { 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) { function findContentByXPath($xpath, array $arguments = array(), $value = NULL) {
$elements = $this->xpath($xpath, $arguments); $elements = $this->xpath($xpath, $arguments);