Add translator documentation.

lib/activity.php

@@ -117,7 +117,8 @@ class Activity
         // Insist on a feed's root DOMElement; don't allow a DOMDocument
         if ($feed instanceof DOMDocument) {
             throw new ClientException(
-                _("Expecting a root feed element but got a whole XML document.")
+                // TRANS: Client exception thrown when a feed instance is a DOMDocument.
+                _('Expecting a root feed element but got a whole XML document.')
             );
         }
 

lib/adminpanelaction.php

@@ -69,7 +69,7 @@ class AdminPanelAction extends Action
         // User must be logged in.
 
         if (!common_logged_in()) {
-            // TRANS: Client error message
+            // TRANS: Client error message thrown when trying to access the admin panel while not logged in.
             $this->clientError(_('Not logged in.'));
             return false;
         }
@@ -94,7 +94,7 @@ class AdminPanelAction extends Action
         // User must have the right to change admin settings
 
         if (!$user->hasRight(Right::CONFIGURESITE)) {
-            // TRANS: Client error message
+            // TRANS: Client error message thrown when a user tries to change admin settings but has no access rights.
             $this->clientError(_('You cannot make changes to this site.'));
             return false;
         }
@@ -106,7 +106,7 @@ class AdminPanelAction extends Action
         $name = mb_substr($name, 0, -10);
 
         if (!self::canAdmin($name)) {
-            // TRANS: Client error message
+            // TRANS: Client error message throw when a certain panel's settings cannot be changed.
             $this->clientError(_('Changes to that panel are not allowed.'), 403);
             return false;
         }
@@ -225,7 +225,7 @@ class AdminPanelAction extends Action
 
     function showForm()
     {
-        // TRANS: Client error message
+        // TRANS: Client error message.
         $this->clientError(_('showForm() not implemented.'));
         return;
     }
@@ -279,7 +279,8 @@ class AdminPanelAction extends Action
             $result = $config->delete();
             if (!$result) {
                 common_log_db_error($config, 'DELETE', __FILE__);
-                // TRANS: Client error message
+                // TRANS: Client error message thrown if design settings could not be deleted in
+                // TRANS: the admin panel Design.
                 $this->clientError(_("Unable to delete design setting."));
                 return null;
             }

lib/apiaction.php

@@ -1065,6 +1065,7 @@ class ApiAction extends Action
             $this->initTwitterAtom();
             break;
         default:
+            // TRANS: Client error on an API request with an unsupported data format.
             $this->clientError(_('Not a supported data format.'));
             break;
         }
@@ -1093,6 +1094,7 @@ class ApiAction extends Action
             $this->endTwitterRss();
             break;
         default:
+            // TRANS: Client error on an API request with an unsupported data format.
             $this->clientError(_('Not a supported data format.'));
             break;
         }
@@ -1209,6 +1211,7 @@ class ApiAction extends Action
             $this->showJsonObjects($profile_array);
             break;
         default:
+            // TRANS: Client error on an API request with an unsupported data format.
             $this->clientError(_('Not a supported data format.'));
             return;
         }

lib/apiauth.php

@@ -91,6 +91,7 @@ class ApiAuthAction extends ApiAction
 
         if ($this->isReadOnly($args) == false) {
             if ($this->access != self::READ_WRITE) {
+                // TRANS: Client error 401.
                 $msg = _('API resource requires read-write access, ' .
                          'but you only have read access.');
                 $this->clientError($msg, 401, $this->format);

lib/applicationeditform.php

@@ -133,6 +133,7 @@ class ApplicationEditForm extends Form
 
     function formLegend()
     {
+        // TRANS: Form legend.
         $this->out->element('legend', null, _('Edit application'));
     }
 
@@ -177,10 +178,12 @@ class ApplicationEditForm extends Form
         }
 
         $this->out->element('label', array('for' => 'app_icon'),
+                            // TRANS: Form input field label for application icon.
                             _('Icon'));
         $this->out->element('input', array('name' => 'app_icon',
                                            'type' => 'file',
                                            'id' => 'app_icon'));
+        // TRANS: Form guide.
         $this->out->element('p', 'form_guide', _('Icon for this application'));
         $this->out->element('input', array('name' => 'MAX_FILE_SIZE',
                                            'type' => 'hidden',
@@ -192,6 +195,7 @@ class ApplicationEditForm extends Form
 
         $this->out->hidden('application_id', $id);
 
+        // TRANS: Form input field label for application name.
         $this->out->input('name', _('Name'),
                           ($this->out->arg('name')) ? $this->out->arg('name') : $name);
 
@@ -201,11 +205,14 @@ class ApplicationEditForm extends Form
 
         $maxDesc = Oauth_application::maxDesc();
         if ($maxDesc > 0) {
+            // TRANS: Form input field instructions.
             $descInstr = sprintf(_('Describe your application in %d characters'),
                                  $maxDesc);
         } else {
+            // TRANS: Form input field instructions.
             $descInstr = _('Describe your application');
         }
+        // TRANS: Form input field label.
         $this->out->textarea('description', _('Description'),
                         ($this->out->arg('description')) ? $this->out->arg('description') : $description,
                              $descInstr);
@@ -213,27 +220,39 @@ class ApplicationEditForm extends Form
         $this->out->elementEnd('li');
 
         $this->out->elementStart('li');
+        // TRANS: Form input field instructions.
+        $instruction = _('URL of the homepage of this application');
+        // TRANS: Form input field label.
         $this->out->input('source_url', _('Source URL'),
                           ($this->out->arg('source_url')) ? $this->out->arg('source_url') : $source_url,
-                          _('URL of the homepage of this application'));
+                          $instruction);
         $this->out->elementEnd('li');
 
         $this->out->elementStart('li');
+        // TRANS: Form input field instructions.
+        $instruction = _('Organization responsible for this application');
+        // TRANS: Form input field label.
         $this->out->input('organization', _('Organization'),
                           ($this->out->arg('organization')) ? $this->out->arg('organization') : $organization,
-                          _('Organization responsible for this application'));
+                          $instruction);
         $this->out->elementEnd('li');
 
         $this->out->elementStart('li');
+        // TRANS: Form input field instructions.
+        $instruction = _('URL for the homepage of the organization');
+        // TRANS: Form input field label.
         $this->out->input('homepage', _('Homepage'),
                           ($this->out->arg('homepage')) ? $this->out->arg('homepage') : $homepage,
-                          _('URL for the homepage of the organization'));
+                          $instruction);
         $this->out->elementEnd('li');
 
         $this->out->elementStart('li');
+        // TRANS: Form input field instructions.
+        $instruction = _('URL to redirect to after authentication');
+        // TRANS: Form input field label.
         $this->out->input('callback_url', ('Callback URL'),
                           ($this->out->arg('callback_url')) ? $this->out->arg('callback_url') : $callback_url,
-                          _('URL to redirect to after authentication'));
+                          $instruction);
         $this->out->elementEnd('li');
 
         $this->out->elementStart('li', array('id' => 'application_types'));
@@ -255,6 +274,7 @@ class ApplicationEditForm extends Form
 
         $this->out->element('label', array('for' => 'app_type-browser',
                                            'class' => 'radio'),
+                            // TRANS: Radio button label for application type
                             _('Browser'));
 
         $attrs = array('name' => 'app_type',
@@ -271,7 +291,9 @@ class ApplicationEditForm extends Form
 
         $this->out->element('label', array('for' => 'app_type-desktop',
                                            'class' => 'radio'),
+                            // TRANS: Radio button label for application type
                             _('Desktop'));
+        // TRANS: Form guide.
         $this->out->element('p', 'form_guide', _('Type of application, browser or desktop'));
         $this->out->elementEnd('li');
 
@@ -294,6 +316,7 @@ class ApplicationEditForm extends Form
 
         $this->out->element('label', array('for' => 'default_access_type-ro',
                                            'class' => 'radio'),
+                            // TRANS: Radio button label for access type.
                             _('Read-only'));
 
         $attrs = array('name' => 'default_access_type',
@@ -312,7 +335,9 @@ class ApplicationEditForm extends Form
 
         $this->out->element('label', array('for' => 'default_access_type-rw',
                                            'class' => 'radio'),
+                            // TRANS: Radio button label for access type.
                             _('Read-write'));
+        // TRANS: Form guide.
         $this->out->element('p', 'form_guide', _('Default access for this application: read-only, or read-write'));
 
         $this->out->elementEnd('li');
@@ -328,9 +353,13 @@ class ApplicationEditForm extends Form
 
     function formActions()
     {
-        $this->out->submit('cancel', _('Cancel'), 'submit form_action-primary',
+        // TRANS: Button label
+        $this->out->submit('cancel', _m('BUTTON','Cancel'), 'submit form_action-primary',
+                           // TRANS: Submit button title
                            'cancel', _('Cancel'));
-        $this->out->submit('save', _('Save'), 'submit form_action-secondary',
+        // TRANS: Button label
+        $this->out->submit('save', _m('BUTTON','Save'), 'submit form_action-secondary',
+                           // TRANS: Submit button title
                            'save', _('Save'));
     }
 }

lib/atomgroupnoticefeed.php

@@ -58,12 +58,14 @@ class AtomGroupNoticeFeed extends AtomNoticeFeed
         parent::__construct($indent);
         $this->group = $group;
 
+        // TRANS: Title in atom group notice feed. %s is a group name.
         $title      = sprintf(_("%s timeline"), $group->nickname);
         $this->setTitle($title);
 
         $sitename   = common_config('site', 'name');
         $subtitle   = sprintf(
-            // TRANS: Message is used as a subtitle. %1$s is a user nickname, %2$s is a site name.
+            // TRANS: Message is used as a subtitle in atom group notice feed.
+            // TRANS: %1$s is a group name, %2$s is a site name.
             _('Updates from %1$s on %2$s!'),
             $group->nickname,
             $sitename

lib/atomusernoticefeed.php

@@ -64,12 +64,14 @@ class AtomUserNoticeFeed extends AtomNoticeFeed
             $this->setActivitySubject($profile->asActivityNoun('subject'));
         }
 
+        // TRANS: Title in atom user notice feed. %s is a user name.
         $title      = sprintf(_("%s timeline"), $user->nickname);
         $this->setTitle($title);
 
         $sitename   = common_config('site', 'name');
         $subtitle   = sprintf(
-            // TRANS: Message is used as a subtitle. %1$s is a user nickname, %2$s is a site name.
+            // TRANS: Message is used as a subtitle in atom user notice feed.
+            // TRANS: %1$s is a user name, %2$s is a site name.
             _('Updates from %1$s on %2$s!'),
             $user->nickname, $sitename
         );

lib/attachmentlist.php

@@ -84,6 +84,7 @@ class AttachmentList extends Widget
         if (empty($att)) return 0;
         $this->out->elementStart('dl', array('id' =>'attachments',
                                              'class' => 'entry-content'));
+        // TRANS: DT element label in attachment list.
         $this->out->element('dt', null, _('Attachments'));
         $this->out->elementStart('dd');
         $this->out->elementStart('ol', array('class' => 'attachments'));
@@ -260,6 +261,7 @@ class Attachment extends AttachmentListItem
                                                   'class' => 'entry-content'));
             if (!empty($this->oembed->author_name)) {
                 $this->out->elementStart('dl', 'vcard author');
+                // TRANS: DT element label in attachment list item.
                 $this->out->element('dt', null, _('Author'));
                 $this->out->elementStart('dd', 'fn');
                 if (empty($this->oembed->author_url)) {
@@ -273,6 +275,7 @@ class Attachment extends AttachmentListItem
             }
             if (!empty($this->oembed->provider)) {
                 $this->out->elementStart('dl', 'vcard');
+                // TRANS: DT element label in attachment list item.
                 $this->out->element('dt', null, _('Provider'));
                 $this->out->elementStart('dd', 'fn');
                 if (empty($this->oembed->provider_url)) {