]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/translation/discussion.mdwn
updated branch; this is ready for review for inclusion in IkIWiki
[git.ikiwiki.info.git] / doc / translation / discussion.mdwn
index 7d4d93c55ff1240ec47a338c59c3720b0eda3797..b274317cd34dc17d93a1b8b834fabb98aa99e642 100644 (file)
@@ -1,3 +1,7 @@
+[[!toc]]
+
+# A few questions about translating PO file
+
 I have a few questions about translating PO file:
 
 1. Assume I copied `ikiwiki.pot` file to `pl.po` file and translated it
@@ -10,20 +14,13 @@ too much about working with PO files in Debian packages.
   > appropriate. ikiwiki should display translated messages when building the
   > wiki (with -v).
 
-2. I'll send you my translation when I finish it, of course. But what about
+2. I'll send you my translation when I finish it, of course. But  about
 updating my PO file? Should I send it to you for every ikiwiki issue?
 Maybe you should give write access to ikiwiki repository for translators
 of PO files?
 
-  > I recently set up a git repository mirroring the main svn repository (see
-  > [[download]]) and one idea is that perhaps translators can use that for a
-  > distributed revision control system that I can merge back from into svn.
-  > I can set up accounts for svn, but as it's on my own personal server and
-  > not a sourceforge/alioth like thing, it's a bit of a pain and maintenance
-  > burden for me.
-
-  >> OK, I've picked up Subversion for your ikiwiki, so I can get into
-  >> Git now ;)
+  > We use git now, so you can clone my repo, commit to your clone, and
+  > use git to mail me patches. --[[Joey]] 
 
 3. What is the best way to update my PO file when you do some changes in
 `ikiwiki.pot` file? Should I translate my PO file from scratch or
@@ -41,13 +38,84 @@ can I do diff for old and new `ikiwiki.pot` file and update only differences?
   >>>> OK, I hope I handle it :)
 
 4. What about "gettexting" button titles and link names? Do you really
-think that there should be hardcoded in ikiwiki templates? --Pawel
+think that there should be hardcoded in ikiwiki templates? --[[Paweł|ptecza]]
 
   > I don't know, really. Recai's approach seems to show promise.
 
   >> BTW, why does ikiwiki number my questions wrongly (1., 1., 1., 1.,
-  >> instead of 1., 2., 3., 4.)? Where have I made a Markdown mistake? --Pawel
+  >> instead of 1., 2., 3., 4.)? Where have I made a Markdown mistake? --[[Paweł|ptecza]]
 
   >>> My indentation mistake, I think. --[[Joey]]
 
-  >>>> Now it's perfect :) Thank you very much! --Pawel
\ No newline at end of file
+  >>>> Now it's perfect :) Thank you very much! --[[Paweł|ptecza]]
+
+----
+
+# Less laconic gettext messages
+
+I'm just translating `ikiwiki.pot` file to Polish and I have
+problems with some gettext messages, because unfortunately
+there are very laconic, for example "update of %s's %s by %s".
+
+Sometimes I don't understand background well, because I don't use
+all ikiwiki plugins and I have to check ikiwiki source code.
+Besides in Polish language we have conjugation of a verb and
+I can't do it correctly if I don't know what subject of
+a message is. Then I have to check the sources again...
+
+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! :) --[[Paweł|ptecza]]
+
+> 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"?
+
+>> But you know that "update of %s's %s by %s" string can be "update of
+>> foowiki's MooBar by joey", but I can only guess it :)
+
+> 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]]
+
+>> Thank you very much! It also will be a big help for me. --[[Paweł|ptecza]]
+
+# Why .po files? Designing an alternative, more user-friendly
+
+I think this plugin is very powerful, and very useful, especially for frontend or vanity sites. However, for live and dynamic sites, edited through the web interface (ie. a wiki!!), the .po file format is very limiting and counter-intuitive for newbies. I know I can fire up emacs and get a nice interface to translate it, but it's not really what I am looking for. .po formats aim to completely translate certain data, while I would expect a wiki to be a bit more lax.
+
+Basically, the problem is that the current plugin assumes the user is familiar with .po files and has a master language, two assumptions that I think are invalid in a lot of cases, especially in "bilingual" or multilingual countries.
+
+One of the canonical examples of functional translation tracking in a wiki is the LizzyWiki, a screencast of which can be seen here: <https://www.youtube.com/watch?v=42kHzyVKsZw> Some of those ideas were implemented in wikis like [[TikiWiki|http://tiki.org/i18n]]
+
+I believe that there are some parts the po plugin that could be reused for such a flexible translation system, in which all languages could be in any format. But basically to implement such a system, those things would be required:
+
+ 1. mapping between pages - this is accomplished by the current po plugin
+ 2. allow the user to flip between pages (other languages links...) - in the current po plugin
+ 3. create a translation based on another page - this is in the current po plugin, but the resulting page is a .po, it should be a regular wiki page
+ 4. track required translations - this is done by gettext in the current po plugin, so this would need to be redone if we change the format
+
+Step 4 is obviously the hard part - tracking changes between pages would involve extra metadata (maybe in the .ikiwiki directory?) to mark which commits have been translated. The metadata is not so much an issue as the user interface problems. 
+
+So say when a user edits page foo.fr.mdwn that is a translation from page foo.en.mdwn, how does he/she tell that the translation is finished or not? The web UI could show the changes that have been done in foo.en.mdwn that need to be translated, and when the user saves the page, he/she is asked to confirm if the page is now completely translated.
+
+Through git only, this would seem to be harder. Maybe if the two translations are committed together they can be assumed to be completely translated, for one. Then maybe there is a way commits could be amended so that they are link - maybe some tree merging magic here? My git internals are a bit far to elaborate on that, and anyways i feel that ikiwiki aims to be RCS agnostic so relying to much on those internals doesn't sound like a good idea.
+
+Obviously, this is a lot more work, diverging in a different direction than the current po-based approach, but it seems to me this is a much more natural system for users.
+
+Also, the thing with the above is that if functionalities 1 and 2 (mapping and page flipping) is stripped out of the po plugin and made reusable, functionalities 3 and 4 can be made optional and a wiki is still translatable, giving the user the responsability of tracking the translations...
+
+So basically, what I think should happen is to have ikiwiki be able to use the .po plugin without .po files - just allow for pages to be linked together. Detect foo.fr.mdwn when parsing foo.mdwn and create links to it would already be a huge start... -- [[anarcat]]
+
+> I have a hopefully clearer spec for a plugin called [[todo/translation_links]]. -- [[anarcat]]