4ad0fa063a88e6429510452b8932b5a15285a440
[ikiwiki.git] / doc / plugins / contrib / po.mdwn
1 I've been working on a plugin called "po", that adds support for multi-lingual wikis,
2 translated with gettext, using [po4a](http://po4a.alioth.debian.org/).
3
4 More information:
5
6 * It can be found in my "po" branch:
7   `git clone git://gaffer.ptitcanardnoir.org/ikiwiki.git`
8 * It is self-contained, *i.e.* it does not modify ikiwiki core at all.
9 * It is documented (including TODO and plans for next work steps) in
10   `doc/plugins/po.mdwn`, which can be found in the same branch.
11 * No public demo site is available so far, I'm working on this.
12
13 My plan is to get this plugin clean enough to be included in ikiwiki.
14
15 The current version is a proof-of-concept, mature enough for me to dare submitting it here,
16 but I'm prepared to hear various helpful remarks, and to rewrite parts of it as needed.
17
18 Any thoughts on this?
19
20 > Well, I think it's pretty stunning what you've done here. Seems very
21 > complete and well thought out. I have not read the code in great detail
22 > yet.
23
24 > Just using po files is an approach I've never seen tried with a wiki. I
25 > suspect it will work better for some wikis than others. For wikis that
26 > just want translations that match the master language as closely as
27 > possible and don't wander off and diverge, it seems perfect. (But what happens
28 > if someone edits the Discussion page of a translated page?)
29
30 > Please keep me posted, when you get closer to having all issues solved
31 > and ready for merging I can do a review and hopefully help with the
32 > security items you listed. --[[Joey]]
33
34 >> Thanks a lot for your quick review, it's reassuring to hear such nice words
35 >> from you. I did not want to design and write a full translation system, when
36 >> tools such as gettext/po4a already have all the needed functionality, for cases
37 >> where the master/slave languages paradigm fits.
38 >> Integrating these tools into ikiwiki plugin system was a pleasure.
39 >>
40 >> I'll tell you when I'm ready for merging, but in the meantime,
41 >> I'd like you to review the changes I did to the core (3 added hooks).
42 >> Can you please do this? If not, I'll go on and hope I'm not going to far in
43 >> the wrong direction.
44 >>
45 >>> Sure.. I'm not completly happy with any of the hooks since they're very
46 >>> special purpose, and also since `run_hooks` is not the best interface
47 >>> for a hook that modifies a variable, where only the last hook run will
48 >>> actually do anything. It might be better to just wrap
49 >>> `targetpage`, `bestlink`, and `beautify_urlpath`. But, I noticed
50 >>> the other day that such wrappers around exported functions are only visible by
51 >>> plugins loaded after the plugin that defines them.
52 >>> 
53 >>> Update: Take a look at the new "Function overriding" section of
54 >>> [[plugins/write]]. I think you can just inject wrappers about a few ikiwiki
55 >>> functions, rather than adding hooks. The `inject` function is pretty
56 >>> insane^Wlow level, but seems to work great. --[[Joey]]
57 >>>
58 >>>> Thanks a lot, it seems to be a nice interface for what I was trying to achieve.
59 >>>> I may be forced to wait two long weeks before I have a chance to confirm
60 >>>> this. Stay tuned. --[[intrigeri]]
61 >>>>
62 >>>>> I've updated the plugin to use `inject`. It is now fully self-contained,
63 >>>>> and does not modify the core anymore. --[[intrigeri]]
64 >>
65 >> The Discussion pages issue is something I am not sure about yet. But I will
66 >> probably decide that "slave" pages, being only translations, don't deserve
67 >> a discussion page: the discussion should happen in the language in which the
68 >> pages are written for real, which is the "master" one. --[[intrigeri]]
69 >> 
70 >> I think that's a good decision, you don't want to translate discussion,
71 >> and if the discussion page turns out multilingual, well, se la vi. ;-)
72 >> 
73 >> Relatedly, what happens if a translated page has a broken link, and you
74 >> click on it to edit it? Seems you'd first have to create a master page
75 >> and could only then translate it, right? I wonder if this will be clear
76 >> though to the user.
77 >>
78 >>> Right: a broken link points to the URL that allows to create
79 >>> a page that can either be a new master page or a non-translatable
80 >>> page, depending on `po_translatable_pages` value. The best
81 >>> solution I can thing of is to use [[plugins/edittemplate]] to
82 >>> insert something like "Warning: this is a master page, that must
83 >>> be written in $MASTER_LANGUAGE" into newly created master pages,
84 >>> and maybe another warning message on newly created
85 >>> non-translatable pages. It seems quite doable to me, but in order
86 >>> to avoid breaking existing functionality, it implies to hack a bit
87 >>> [[plugins/edittemplate]] so that multiple templates can be
88 >>> inserted at page creation time. [[--intrigeri]]
89 >>
90 >> And also, is there any way to start a translation of a page into a new
91 >> lanauge using the web interface?
92 >>
93 >>> When a new language is added to `po_slave_languages`, a rebuild is
94 >>> triggered, and all missing PO files are created and checked into
95 >>> VCS. An unpriviledged wiki user can not add a new language to
96 >>> `po_slave_languages`, though. One could thing of adding the needed
97 >>> interface to translate a page into a yet-unsupported slave
98 >>> language, and this would automagically add this new language to
99 >>> `po_slave_languages`. It would probably be useful in some
100 >>> usecases, but I'm not comfortable with letting unpriviledged wiki
101 >>> users change the wiki configuration as a side effect of their
102 >>> actions; if this were to be implemented, special care would be
103 >>> needed. [[--intrigeri]]
104 >>>
105 >>>> Actually I meant into any of the currently supported languages.
106 >>>> I guess that if the template modification is made, it will list those
107 >>>> languages on the page, and if a translation to a language is missing,
108 >>>> the link will allow creating it?
109
110 >> FWIW, I'm tracking your po branch in ikiwiki master git in the po
111 >> branch. One thing I'd like to try in there is setting up a translated
112 >> basewiki, which seems like it should be pretty easy to do, and would be
113 >> a great demo! --[[Joey]]
114 >>
115 >>> I've merged your changes into my own branch, and made great
116 >>> progress on the various todo items. Please note my repository
117 >>> location has changed a few days ago, my user page was updated
118 >>> accordingly, but I forgot to update this page at the same time.
119 >>> Hoping it's not too complicated to relocated an existing remote...
120 >>> (never done that, I'm a Git beginner as well as a Perl
121 >>> newbie) --[[intrigeri]]
122 >>>>
123 >>>> Just a matter of editing .git/config, thanks for the heads up.
124 >>>>>
125 >>>>> Joey, please have a look at my branch, your help would be really
126 >>>>> welcome for the security research, as I'm almost done with what
127 >>>>> I am able to do myself in this area. --[[intrigeri]]