add spec dependency

[ikiwiki] / doc / translation / discussion.mdwn

[[!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
from English to Polish. How can I check that my `pl.po` file works good?
I have some experience with building Debian packages, but I don't know
too much about working with PO files in Debian packages.

  > Try putting it into the po/ directory and running make and make install
  > in there, that should create the .mo and install it somewhere
  > 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  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?

  > 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
can I do diff for old and new `ikiwiki.pot` file and update only differences?

  > There are standard tools for working with po files, and the po file
  > should be updated as part of the wiki build process so that any fuzzy
  > strings are so marked.

  >> Could you please point me any good references or write a quick start
  >> for translators? I think it can be very useful for me and other people.

  >>> I'm not a translator, so I don't really know..

  >>>> 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? --[[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? --[[Paweł|ptecza]]

  >>> My indentation mistake, I think. --[[Joey]]

  >>>> 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]]