added some comments for translators

9 files changed, 72 insertions, 16 deletions

diff --git a/IkiWiki.pm b/IkiWiki.pm
index 8f7d8d20b..5b78014d1 100644
--- a/IkiWiki.pm
+++ b/IkiWiki.pm
@@ -517,6 +517,10 @@ sub preprocess ($$$;$) { #{{{
 			if ($preprocessing{$page}++ > 3) {
 				# Avoid loops of preprocessed pages preprocessing
 				# other pages that preprocess them, etc.
+				#translators: The first parameter is a
+				#translators: preprocessor directive name,
+				#translators: the second a page name, the
+				#translators: third a number.
 				return "[[".sprintf(gettext("%s preprocessing loop detected on %s at depth %i"),
 					$command, $page, $preprocessing{$page}).
 				"]]";
diff --git a/IkiWiki/CGI.pm b/IkiWiki/CGI.pm
index 5d21d0674..85fc1a386 100644
--- a/IkiWiki/CGI.pm
+++ b/IkiWiki/CGI.pm
@@ -46,6 +46,8 @@ sub page_locked ($$;$) { #{{{
 		if (pagespec_match($page, userinfo_get($admin, "locked_pages"))) {
 			return 1 if $nonfatal;
 
+			#translators: The first parameter is a page name,
+			#translators: second is the user who locked it.
 			error(sprintf(gettext("%s is locked by %s and cannot be edited"),
 				htmllink("", "", $page, 1),
 				userlink($admin)));
diff --git a/IkiWiki/Plugin/shortcut.pm b/IkiWiki/Plugin/shortcut.pm
index 9479306a8..2a4a36a41 100644
--- a/IkiWiki/Plugin/shortcut.pm
+++ b/IkiWiki/Plugin/shortcut.pm
@@ -27,6 +27,9 @@ sub preprocess_shortcut (@) { #{{{
 	hook(type => "preprocess", no_override => 1, id => $params{name},
 		call => sub { shortcut_expand($params{url}, $params{desc}, @_) });
 
+	#translators: This is used to display what shortcuts are defined.
+	#translators: First parameter is the name of the shortcut, the second
+	#translators: is an URL.
 	return sprintf(gettext("shortcut %s points to %s"), $params{name}, $params{url});
 } # }}}
 
diff --git a/IkiWiki/Setup.pm b/IkiWiki/Setup.pm
index 560bc798b..2d6e1d1cf 100644
--- a/IkiWiki/Setup.pm
+++ b/IkiWiki/Setup.pm
@@ -10,6 +10,8 @@ package IkiWiki;
 sub setup () { # {{{
 	my $setup=possibly_foolish_untaint($config{setup});
 	delete $config{setup};
+	#translators: The first parameter is a filename, and the second
+	#translators: is a (probably not translated) error message.
 	open (IN, $setup) || error(sprintf(gettext("cannot read %s: %s"), $setup, $!));
 	my $code;
 	{
diff --git a/IkiWiki/UserInfo.pm b/IkiWiki/UserInfo.pm
index 03d63cc23..267f5d9cd 100644
--- a/IkiWiki/UserInfo.pm
+++ b/IkiWiki/UserInfo.pm
@@ -132,6 +132,10 @@ sub send_commit_mails ($$$@) { #{{{
 		else {
 			$pagelist.=join(" ", @changed_pages);
 		}
+		#translators: The three variables are the name of the wiki,
+		#translators: A list of one or more pages that were changed,
+		#translators: And the name of the user making the change.
+		#translators: This is used as the subject of a commit email.
 		my $subject=sprintf(gettext("update of %s's %s by %s"), 
 			$config{wikiname}, $pagelist, $user);
 
diff --git a/IkiWiki/Wrapper.pm b/IkiWiki/Wrapper.pm
index e761085fb..beabc5649 100644
--- a/IkiWiki/Wrapper.pm
+++ b/IkiWiki/Wrapper.pm
@@ -59,6 +59,8 @@ EOF
 	$configstring=~s/"/\\"/g;
 	$configstring=~s/\n/\\\n/g;
 	
+	#translators: The first parameter is a filename, and the second is
+	#translators: a (probably not translated) error message.
 	open(OUT, ">$wrapper.c") || error(sprintf(gettext("failed to write %s: %s"), "$wrapper.c", $!));;
 	print OUT <<"EOF";
 /* A wrapper for ikiwiki, can be safely made suid. */
@@ -94,6 +96,7 @@ $envsave
 EOF
 	close OUT;
 	if (system("gcc", "$wrapper.c", "-o", $wrapper) != 0) {
+		#translators: The parameter is a C filename.
 		error(sprintf(gettext("failed to compile %s"), "$wrapper.c"));
 	}
 	unlink("$wrapper.c");
@@ -101,6 +104,7 @@ EOF
 	    ! chmod(oct($config{wrappermode}), $wrapper)) {
 		error("chmod $wrapper: $!");
 	}
+	#translators: The parameter is a filename.
 	printf(gettext("successfully generated %s\n"), $wrapper);
 } #}}}
 
diff --git a/doc/translation/discussion.mdwn b/doc/translation/discussion.mdwn
index 32cc3f5e9..1ee89d57d 100644
--- a/doc/translation/discussion.mdwn
+++ b/doc/translation/discussion.mdwn
@@ -72,3 +72,21 @@ So I have a request to Joey and the rest of ikiwiki coders:
 please write more verbose gettext messages and don't fear using
 subject there. It will be huge help for me and other ikiwiki
 translators. Thank you! :) --Pawel
+
+> Well, those messages are mostly laconic because they're output by
+> ikiwiki running in unix program mode and other tight situations, and 
+> it should be clear from context when you see the expanded message what
+> the various bits are. 
+> 
+> For example, "update of foowiki's MooBar by joey" seems to say enough to
+> be clear (and fit in mutt's subject line display), while the corresponding
+> "actualizado el wiki foowiki y la página MooBar por el usuario joey" feels
+> a bit verbose. (And should it say "updated foowiki *and* the MooBar page"
+> like that? My Spanish sucks though..) In my crappy Spanish I might instead
+> say something like "actualizado MooBar de foowiki por joey". Or maybe
+> "actualizado página Moobar por joey"?
+> 
+> Anyway, to get back to your point, it's true that translators often
+> need additonal context about things like what variables expand to, and
+> size limits. This is generally done by adding comments in the pot file,
+> and I've turned that on, and added a few. --[[Joey]]
diff --git a/po/Makefile b/po/Makefile
index 910114e67..2d34c6fe8 100644
--- a/po/Makefile
+++ b/po/Makefile
@@ -16,7 +16,7 @@ install: all
 
 ikiwiki.pot: $(POTFILES)
 	@echo "Rebuilding the pot file"
-	xgettext $(POTFILES) -o ikiwiki.pot -Lperl
+	xgettext $(POTFILES) -o ikiwiki.pot -Lperl --add-comments=translators
 
 clean:
 	rm -f ikiwiki.pot $(MOFILES) messages messages.mo
diff --git a/po/es.po b/po/es.po
index a384e566f..619171f8c 100644
--- a/po/es.po
+++ b/po/es.po
@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: ikiwiki\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2007-01-03 14:11-0500\n"
+"POT-Creation-Date: 2007-01-04 06:58-0500\n"
 "PO-Revision-Date: 2007-01-03 09:37+0100\n"
 "Last-Translator: Víctor Moral <victor@taquiones.net>\n"
 "Language-Team: spanish <es@li.org>\n"
@@ -16,35 +16,37 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "X-Generator: KBabel 1.11.4\n"
 
-#: ../IkiWiki/CGI.pm:49
+#. translators: The first parameter is a page name,
+#. translators: second is the user who locked it.
+#: ../IkiWiki/CGI.pm:51
 #, perl-format
 msgid "%s is locked by %s and cannot be edited"
 msgstr "La página %s está bloqueada por %s y no puede modificarse"
 
-#: ../IkiWiki/CGI.pm:139
+#: ../IkiWiki/CGI.pm:141
 msgid "You need to log in first."
 msgstr "Antes es necesario identificarse"
 
-#: ../IkiWiki/CGI.pm:257
+#: ../IkiWiki/CGI.pm:259
 msgid "Preferences saved."
 msgstr "Las preferencias se han guardado."
 
-#: ../IkiWiki/CGI.pm:408 ../IkiWiki/Plugin/inline.pm:162
+#: ../IkiWiki/CGI.pm:410 ../IkiWiki/Plugin/inline.pm:162
 #: ../IkiWiki/Render.pm:97 ../IkiWiki/Render.pm:161
 msgid "discussion"
 msgstr "comentarios"
 
-#: ../IkiWiki/CGI.pm:447
+#: ../IkiWiki/CGI.pm:449
 #, perl-format
 msgid "creating %s"
 msgstr "creando página %s"
 
-#: ../IkiWiki/CGI.pm:464 ../IkiWiki/CGI.pm:507
+#: ../IkiWiki/CGI.pm:466 ../IkiWiki/CGI.pm:509
 #, perl-format
 msgid "editing %s"
 msgstr "modificando página %s"
 
-#: ../IkiWiki/CGI.pm:624
+#: ../IkiWiki/CGI.pm:626
 msgid "You are banned."
 msgstr "Ha sido expulsado."
 
@@ -211,7 +213,10 @@ msgstr "actualizando el índice de búsquedas de hyperstraier"
 msgid "shortcut missing name or url parameter"
 msgstr "shortcut necesita el párametro name ó el parámetro url"
 
-#: ../IkiWiki/Plugin/shortcut.pm:30
+#. translators: This is used to display what shortcuts are defined.
+#. translators: First parameter is the name of the shortcut, the second
+#. translators: is an URL.
+#: ../IkiWiki/Plugin/shortcut.pm:33
 #, perl-format
 msgid "shortcut %s points to %s"
 msgstr "El atajo %s lleva a %s"
@@ -296,7 +301,9 @@ msgstr "eliminando la página %s puesto que ya no se deriva de %s"
 msgid "ikiwiki: cannot render %s"
 msgstr "ikwiki: no puedo convertir la página %s"
 
-#: ../IkiWiki/Setup.pm:13
+#. translators: The first parameter is a filename, and the second
+#. translators: is a (probably not translated) error message.
+#: ../IkiWiki/Setup.pm:15
 #, perl-format
 msgid "cannot read %s: %s"
 msgstr "no puedo leer el archivo %s: %s"
@@ -317,7 +324,11 @@ msgstr "actualizando el wiki.."
 msgid "done"
 msgstr "completado"
 
-#: ../IkiWiki/UserInfo.pm:135
+#. translators: The three variables are the name of the wiki,
+#. translators: A list of one or more pages that were changed,
+#. translators: And the name of the user making the change.
+#. translators: This is used as the subject of a commit email.
+#: ../IkiWiki/UserInfo.pm:139
 #, perl-format
 msgid "update of %s's %s by %s"
 msgstr "actualizado el wiki %s y la página %s por el usuario %s"
@@ -336,17 +347,21 @@ msgstr ""
 msgid "wrapper filename not specified"
 msgstr "el programa envoltorio no ha sido especificado"
 
-#: ../IkiWiki/Wrapper.pm:62
+#. translators: The first parameter is a filename, and the second is
+#. translators: a (probably not translated) error message.
+#: ../IkiWiki/Wrapper.pm:64
 #, perl-format
 msgid "failed to write %s: %s"
 msgstr "no puedo escribir en %s: %s"
 
-#: ../IkiWiki/Wrapper.pm:97
+#. translators: The parameter is a C filename.
+#: ../IkiWiki/Wrapper.pm:100
 #, perl-format
 msgid "failed to compile %s"
 msgstr "ha fallado la compilación del programa envoltorio %s"
 
-#: ../IkiWiki/Wrapper.pm:104
+#. translators: The parameter is a filename.
+#: ../IkiWiki/Wrapper.pm:108
 #, perl-format
 msgid "successfully generated %s\n"
 msgstr "creado con éxito el programa envoltorio %s\n"
@@ -365,7 +380,11 @@ msgstr ""
 msgid "Error"
 msgstr "Error"
 
-#: ../IkiWiki.pm:520
+#. translators: The first parameter is a
+#. translators: preprocessor directive name,
+#. translators: the second a page name, the
+#. translators: third a number.
+#: ../IkiWiki.pm:524
 #, perl-format
 msgid "%s preprocessing loop detected on %s at depth %i"
 msgstr ""