fixed one security problem, two more need review

[git.ikiwiki.info.git] / doc / plugins / po.mdwn

diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index b3c50a925a067cfc19d4d297d064bbc2ac730d09..ba293f26241822f16925406b76b59ce8868546c7 100644 (file)
--- a/doc/plugins/po.mdwn
+++ b/doc/plugins/po.mdwn
@@ -13,7 +13,7 @@ A language is chosen as the "master" one, and any other supported
 language is a "slave" one.
 
 A page written in the "master" language is a "master" page. It can be
 language is a "slave" one.
 
 A page written in the "master" language is a "master" page. It can be

-of any page type supported by ikiwiki, but PO. It does not have to be
+of any page type supported by ikiwiki, except `po`. It does not have to be

 named a special way: migration to this plugin does not imply any page
 renaming work.
 
 named a special way: migration to this plugin does not imply any page
 renaming work.
 


@@ -22,7 +22,7 @@ English; if `usedirs` is enabled, it is rendered as
 `bla/page/index.en.html`, else as `bla/page.en.html`.
 
 Any translation of a "master" page into a "slave" language is called
 `bla/page/index.en.html`, else as `bla/page.en.html`.
 
 Any translation of a "master" page into a "slave" language is called

-a "slave" page; it is written in the gettext PO format. PO is now
+a "slave" page; it is written in the gettext PO format. `po` is now

 a page type supported by ikiwiki.
 
 Example: `bla/page.fr.po` is the PO "message catalog" used to
 a page type supported by ikiwiki.
 
 Example: `bla/page.fr.po` is the PO "message catalog" used to


@@ -56,9 +56,8 @@ The `po_translatable_pages` setting configures what pages are
 translatable. It is a [[ikiwiki/PageSpec]], so you have lots of
 control over what kind of pages are translatable.
 
 translatable. It is a [[ikiwiki/PageSpec]], so you have lots of
 control over what kind of pages are translatable.
 

-The PO translations files are anyway not considered as being
-translatable, so you don't need to worry about excluding them
-explicitly from this [[ikiwiki/PageSpec]].
+The `.po` files are not considered as being translatable, so you don't need to
+worry about excluding them explicitly from this [[ikiwiki/PageSpec]].

 
 Internal links
 --------------
 
 Internal links
 --------------


@@ -128,6 +127,9 @@ Usage
 Templates
 ---------
 
 Templates
 ---------
 

+The `ISTRANSLATION` and `ISTRANSLATABLE` variables can be used to
+display things only on translatable or translation pages.
+

 ### Display page's versions in other languages
 
 The `OTHERLANGUAGES` loop provides ways to display other languages'
 ### Display page's versions in other languages
 
 The `OTHERLANGUAGES` loop provides ways to display other languages'


@@ -163,28 +165,49 @@ The following variables are available inside the loop (for every page in):
 The `PERCENTTRANSLATED` variable is set to the translation
 completeness, expressed in percent, on "slave" pages.
 
 The `PERCENTTRANSLATED` variable is set to the translation
 completeness, expressed in percent, on "slave" pages.
 

+One can use it this way:
+
+       <TMPL_IF NAME="ISTRANSLATION">
+       <div id="percenttranslated">
+         <TMPL_VAR NAME="PERCENTTRANSLATED">
+       </div>
+       </TMPL_IF>
+

 Additional PageSpec tests
 -------------------------
 
 This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with some
 additional tests that are documented [[here|ikiwiki/pagespec/po]].
 
 Additional PageSpec tests
 -------------------------
 
 This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with some
 additional tests that are documented [[here|ikiwiki/pagespec/po]].
 

-Automatic PO files update
--------------------------
+Automatic PO file update
+------------------------

 
 Committing changes to a "master" page:
 
 
 Committing changes to a "master" page:
 

-1. updates the POT file and the PO files for the supported languages
-   (this is done in the `needsbuild` hook); the updated PO files are
-   then put under version control
-2. triggers a refresh of the corresponding HTML slave pages (this is
-   achieved by making any "slave" page dependent on the corresponding
-   "master" page, in the `needsbuild` hook)
+1. updates the POT file and the PO files for the supported languages;
+   the updated PO files are then put under version control
+2. triggers a refresh of the corresponding HTML slave pages

 
 Also, when the plugin has just been enabled, or when a page has just
 been declared as being translatable, the needed POT and PO files are
 created, and the PO files are checked into version control.
 
 
 Also, when the plugin has just been enabled, or when a page has just
 been declared as being translatable, the needed POT and PO files are
 created, and the PO files are checked into version control.
 

+Discussion pages
+----------------
+
+Discussion should happen in the language in which the pages are written for
+real, *i.e.* the "master" one. If discussion pages are enabled, "slave" pages
+therefore link to the "master" page's discussion page.
+
+Translating
+-----------
+
+One can edit the PO files using ikiwiki's CGI (a message-by-message interface
+could also be implemented at some point).
+
+If [[tips/untrusted_git_push]] is setup, one can edit the PO files in one's
+preferred `$EDITOR`, without needing to be online.
+

 TODO
 ====
 
 TODO
 ====
 


@@ -204,62 +227,81 @@ Security checks
 
 - `refreshpofiles` uses `system()`, whose args have to be checked more
   thoroughly to prevent any security issue (command injection, etc.).
 
 - `refreshpofiles` uses `system()`, whose args have to be checked more
   thoroughly to prevent any security issue (command injection, etc.).

+  > Always pass `system()` a list of parameters to avoid the shell.
+  > I've checked in a change fixing that. --[[Joey]]

 - `refreshpofiles` and `refreshpot` create new files; this may need
   some checks, e.g. using `IkiWiki::prep_writefile()`
 - `refreshpofiles` and `refreshpot` create new files; this may need
   some checks, e.g. using `IkiWiki::prep_writefile()`

+- Can any sort of directives be put in po files that will
+  cause mischief (ie, include other files, run commands, crash gettext,
+  whatever).
+- Any security issues on running po4a on untrusted content?

 
 gettext/po4a rough corners
 --------------------------
 
 
 gettext/po4a rough corners
 --------------------------
 

-- fix the "duplicate message definition" error when updating a PO
-  file; do PO files need normalizing?
-- should `*.po~` backup files really be saved?
+- fix infinite loop when synchronizing two ikiwiki (when checkouts
+  live in different directories): say bla.fr.po has been updated in
+  repo2; pulling repo2 from repo1 seems to trigger a PO update, that
+  changes bla.fr.po in repo1; then pushing repo1 to repo2 triggers
+  a PO update, that changes bla.fr.po in repo2; etc.; fixed in
+  `629968fc89bced6727981c0a1138072631751fee`?
+- new translations created in the web interface must get proper charset/encoding
+  gettext metadata, else the next automatic PO update removes any non-ascii
+  chars; possible solution: put such metadata into the Pot file, and let it
+  propagate; should be fixed in `773de05a7a1ee68d2bed173367cf5e716884945a`, time
+  will tell.
+
+Misc. improvements
+------------------

 
 

-Translation quality assurance
------------------------------
+### preview

 
 

-Modifying a PO file via the CGI must be forbidden if the new version
-is not a valid PO file. As a bonus, check that it provides a more
-complete translation than the existing one.
+preview does not work for PO files.

 
 

-A new `cansave` type of hook would be needed to implement this.
+### automatic POT/PO update

 
 

-Note: committing to the underlying repository is a way to bypass
-this check.
+Use the `change` hook instead of `needsbuild`?

 
 

-Translating online
-------------------
+### page titles
+
+Use nice page titles from meta plugin in links, as inline already does. This is
+actually a duplicate for
+[[bugs/pagetitle_function_does_not_respect_meta_titles]], which might be fixed
+by something like [[todo/using_meta_titles_for_parentlinks]].
+
+### websetup
+
+Which configuration settings are safe enough for websetup?

 
 

-As PO is a wiki page type, we already have an online PO editor, that
-is ikiwiki's CGI.
+> I see no problems with `po_master_language` and `po_slave_languages`
+> (assuming websetup handles the hashes correctly). Would not hurt to check
+> that the values of these are legal language codes, in `checkconfig`. 
+> `po_translatable_pages` seems entirely safe. `po_link_to` w/o usedirs
+> causes ikiwiki to error out. If it were changed to fall back to a safe
+> setting in this case rather than error, it would be safe.
+> --[[Joey]]

 
 

-A message-by-message interface could also be implemented at some
-point; a nice way to do offline translation work (without VCS access)
-still has to be offered, though.
+### parentlinks

 
 

-Translating offline without VCS access
---------------------------------------
+When the wiki home page is translatable, the parentlinks plugin sets
+`./index.html` as its translations' single parent link. Ideally, the home page's
+translations should get no parent link at all, just like the version written in
+the master language.

 
 

-The following workflow should be made possible for translators without
-VCS access who need to edit the PO files in another editor than a web
-browser:
+### backlinks

 
 

-- download the page's PO file
-- use any PO editor to update the translation
-- upload the updated PO file
+If a given translatable `sourcepage.mdwn` links to \[[destpage]],
+`sourcepage.LL.po` also link to \[[destpage]], and the latter has the master
+page *and* all its translations listed in the backlinks.

 
 

-Implementation note: a generic mechanism to upload a page's source is
-needed: it's only an alternative way to allow saving a the modified
-page's source with the CGI.
+Translation quality assurance
+-----------------------------

 
 

-### Short-term workflow
+Modifying a PO file via the CGI must be forbidden if the new version
+is not a valid PO file. As a bonus, check that it provides a more
+complete translation than the existing one.

 
 

-A possible workaround is:
+A new `cansave` type of hook would be needed to implement this.

 
 

-- pretend to edit the PO file online
-- copy the PO file content from the textarea
-- cancel the edit
-- paste the content into a local file.
-- edit the local file in any PO editor
-- pretend to edit the PO file online
-- paste the modified local file's content into the edit textarea
-- save
+Note: committing to the underlying repository is a way to bypass
+this check.