From 2739843e2bb794636baa87f26e6d3a4dfa64a529 Mon Sep 17 00:00:00 2001
From: Johan Falk <johan.falk@nodeone.se>
Date: Fri, 11 Mar 2011 16:05:48 +0100
Subject: [PATCH] Issue #1045396 by Itangalo: Commenting and clarification of translation.pages.inc.

---
 modules/translation/translation.pages.inc |   62 ++++++++++++++++++++++-------
 1 files changed, 47 insertions(+), 15 deletions(-)

diff --git a/modules/translation/translation.pages.inc b/modules/translation/translation.pages.inc
index 102d1b8..2f4e886 100644
--- a/modules/translation/translation.pages.inc
+++ b/modules/translation/translation.pages.inc
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * User page callbacks for the translation module.
+ * Page callback for the node translation overview page.
  */
 
 /**
@@ -14,59 +14,91 @@
 function translation_node_overview($node) {
   include_once DRUPAL_ROOT . '/includes/language.inc';
 
+  // Set the page title.
+  drupal_set_title(t('Translations of %title', array('%title' => $node->title)), PASS_THROUGH);
+
+  // Grab the translation set and the translations for the node.
   if ($node->tnid) {
-    // Already part of a set, grab that set.
+    // If the node is already part of a set, grab that set.
     $tnid = $node->tnid;
     $translations = translation_node_get_translations($node->tnid);
   }
   else {
-    // We have no translation source nid, this could be a new set, emulate that.
+    // If we have no translation set, emulate that this is the source node.
     $tnid = $node->nid;
     $translations = array($node->language => $node);
   }
 
   $type = variable_get('translation_language_type', LANGUAGE_TYPE_INTERFACE);
+
+  // Start building a table holding translation information and links.
   $header = array(t('Language'), t('Title'), t('Status'), t('Operations'));
 
+  // Build one row for each enabled language on the website.
   foreach (language_list() as $langcode => $language) {
     $options = array();
     $language_name = $language->name;
+
     if (isset($translations[$langcode])) {
-      // Existing translation in the translation set: display status.
-      // We load the full node to check whether the user can edit it.
+      // For existing translation in the translation set: display their status.
+      // We load the full node to check whether the user can edit it, and also
+      // for a number of other checks of node data.
       $translation_node = node_load($translations[$langcode]->nid);
+
+      // Set the language in strong style if it is the source language.
+      if ($translation_node->nid == $tnid) {
+        $language_name = t('<strong>@language_name</strong> (source)',
+          array('@language_name' => $language_name));
+      }
+
+      // Get language prefix (or other link format) for the node on this row.
       $path = 'node/' . $translation_node->nid;
       $links = language_negotiation_get_switch_links($type, $path);
-      $title = empty($links->links[$langcode]) ? l($translation_node->title, $path) : l($translation_node->title, $links->links[$langcode]['href'], $links->links[$langcode]);
+
+      // Set the node title, including a somewhat cumbersome link URL.
+      $title = empty($links->links[$langcode]) ?
+        l($translation_node->title, $path) :
+        l($translation_node->title, $links->links[$langcode]['href'], $links->links[$langcode]);
+
+      // Set an edit link as an option, if the user can edit the node.
       if (node_access('update', $translation_node)) {
         $text = t('edit');
         $path = 'node/' . $translation_node->nid . '/edit';
         $links = language_negotiation_get_switch_links($type, $path);
-        $options[] = empty($links->links[$langcode]) ? l($text, $path) : l($text, $links->links[$langcode]['href'], $links->links[$langcode]);
+        $options[] = empty($links->links[$langcode]) ? l($text, $path) :
+          l($text, $links->links[$langcode]['href'], $links->links[$langcode]);
       }
+
+      // Set published status and also mark if translation needs update.
       $status = $translation_node->status ? t('Published') : t('Not published');
-      $status .= $translation_node->translate ? ' - <span class="marker">' . t('outdated') . '</span>' : '';
-      if ($translation_node->nid == $tnid) {
-        $language_name = t('<strong>@language_name</strong> (source)', array('@language_name' => $language_name));
-      }
+      $status .= $translation_node->translate ?
+        ' - <span class="marker">' . t('outdated') . '</span>' : '';
     }
+
     else {
-      // No such translation in the set yet: help user to create it.
+      // If the current node isn't translated to the language on this row.
       $title = t('n/a');
+
+      // Set a link to create a translation, if the user has access to do so.
       if (node_access('create', $node)) {
         $text = t('add translation');
         $path = 'node/add/' . str_replace('_', '-', $node->type);
         $links = language_negotiation_get_switch_links($type, $path);
         $query = array('query' => array('translation' => $node->nid, 'target' => $langcode));
-        $options[] = empty($links->links[$langcode]) ? l($text, $path, $query) : l($text, $links->links[$langcode]['href'], array_merge_recursive($links->links[$langcode], $query));
+
+        // Set the create translation as an option, including a cumbersome link.
+        $options[] = empty($links->links[$langcode]) ? l($text, $path, $query) :
+          l($text, $links->links[$langcode]['href'],
+            array_merge_recursive($links->links[$langcode], $query));
       }
       $status = t('Not translated');
     }
+
+    // Set a table row for this language, with all data collected above.
     $rows[] = array($language_name, $title, $status, implode(" | ", $options));
   }
 
-  drupal_set_title(t('Translations of %title', array('%title' => $node->title)), PASS_THROUGH);
-
+  // Collect table data in a single array, and return the result.
   $build['translation_node_overview'] = array(
     '#theme' => 'table',
     '#header' => $header,
-- 
1.7.1