elaborate an alternative to po-based translation systems, more user-friendly
[ikiwiki.git] / doc / translation / discussion.mdwn
1 [[!toc]]
2
3 # A few questions about translating PO file
4
5 I have a few questions about translating PO file:
6
7 1. Assume I copied `ikiwiki.pot` file to `pl.po` file and translated it
8 from English to Polish. How can I check that my `pl.po` file works good?
9 I have some experience with building Debian packages, but I don't know
10 too much about working with PO files in Debian packages.
11
12   > Try putting it into the po/ directory and running make and make install
13   > in there, that should create the .mo and install it somewhere
14   > appropriate. ikiwiki should display translated messages when building the
15   > wiki (with -v).
16
17 2. I'll send you my translation when I finish it, of course. But  about
18 updating my PO file? Should I send it to you for every ikiwiki issue?
19 Maybe you should give write access to ikiwiki repository for translators
20 of PO files?
21
22   > We use git now, so you can clone my repo, commit to your clone, and
23   > use git to mail me patches. --[[Joey]] 
24
25 3. What is the best way to update my PO file when you do some changes in
26 `ikiwiki.pot` file? Should I translate my PO file from scratch or
27 can I do diff for old and new `ikiwiki.pot` file and update only differences?
28
29   > There are standard tools for working with po files, and the po file
30   > should be updated as part of the wiki build process so that any fuzzy
31   > strings are so marked.
32
33   >> Could you please point me any good references or write a quick start
34   >> for translators? I think it can be very useful for me and other people.
35
36   >>> I'm not a translator, so I don't really know..
37
38   >>>> OK, I hope I handle it :)
39
40 4. What about "gettexting" button titles and link names? Do you really
41 think that there should be hardcoded in ikiwiki templates? --[[Paweł|ptecza]]
42
43   > I don't know, really. Recai's approach seems to show promise.
44
45   >> BTW, why does ikiwiki number my questions wrongly (1., 1., 1., 1.,
46   >> instead of 1., 2., 3., 4.)? Where have I made a Markdown mistake? --[[Paweł|ptecza]]
47
48   >>> My indentation mistake, I think. --[[Joey]]
49
50   >>>> Now it's perfect :) Thank you very much! --[[Paweł|ptecza]]
51
52 ----
53
54 # Less laconic gettext messages
55
56 I'm just translating `ikiwiki.pot` file to Polish and I have
57 problems with some gettext messages, because unfortunately
58 there are very laconic, for example "update of %s's %s by %s".
59
60 Sometimes I don't understand background well, because I don't use
61 all ikiwiki plugins and I have to check ikiwiki source code.
62 Besides in Polish language we have conjugation of a verb and
63 I can't do it correctly if I don't know what subject of
64 a message is. Then I have to check the sources again...
65
66 So I have a request to Joey and the rest of ikiwiki coders:
67 please write more verbose gettext messages and don't fear using
68 subject there. It will be huge help for me and other ikiwiki
69 translators. Thank you! :) --[[Paweł|ptecza]]
70
71 > Well, those messages are mostly laconic because they're output by
72 > ikiwiki running in unix program mode and other tight situations, and 
73 > it should be clear from context when you see the expanded message what
74 > the various bits are. 
75
76 > For example, "update of foowiki's MooBar by joey" seems to say enough to
77 > be clear (and fit in mutt's subject line display), while the corresponding
78 > "actualizado el wiki foowiki y la página MooBar por el usuario joey" feels
79 > a bit verbose. (And should it say "updated foowiki *and* the MooBar page"
80 > like that? My Spanish sucks though..) In my crappy Spanish I might instead
81 > say something like "actualizado MooBar de foowiki por joey". Or maybe
82 > "actualizado página Moobar por joey"?
83
84 >> But you know that "update of %s's %s by %s" string can be "update of
85 >> foowiki's MooBar by joey", but I can only guess it :)
86
87 > Anyway, to get back to your point, it's true that translators often
88 > need additonal context about things like what variables expand to, and
89 > size limits. This is generally done by adding comments in the pot file,
90 > and I've turned that on, and added a few. --[[Joey]]
91
92 >> Thank you very much! It also will be a big help for me. --[[Paweł|ptecza]]
93
94 # Why .po files? Designing an alternative, more user-friendly
95
96 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.
97
98 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.
99
100 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]]
101
102 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:
103
104  1. mapping between pages - this is accomplished by the current po plugin
105  2. allow the user to flip between pages (other languages links...) - in the current po plugin
106  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
107  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
108
109 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. 
110
111 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.
112
113 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.
114
115 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. -- [[anarcat]]