[GNUnet-SVN] r4210 - in i18nHTML: . src/examples

[grothoff]

Author: grothoff
Date: 2007-01-06 00:59:34 -0800 (Sat, 06 Jan 2007)
New Revision: 4210

Modified:
   i18nHTML/README
   i18nHTML/src/examples/example.php
   i18nHTML/src/examples/example2.php
   i18nHTML/src/examples/start.php
   i18nHTML/todo
Log:
docs

Modified: i18nHTML/README
===================================================================
--- i18nHTML/README     2007-01-06 08:32:34 UTC (rev 4209)
+++ i18nHTML/README     2007-01-06 08:59:34 UTC (rev 4210)
@@ -10,107 +10,95 @@
 be updated without loosing existing translations for sentences that
 were not changed.
 
+For examples on how to write internationalized webpages with i18nHTML
+please look in the src/examples/ directory.  You do not need to install 
+those pages; however, you may want to offer some of the content of the
+"start.php" page as an introduction to i18nHTML to your translators.
+
+
+INSTALLATION
+============
+
 src/i18nHTML/ contains PHP scripts that should be copied into a
-subdirectory "i18nHTML/" of a directory listed in the include_path
-from php.init (i.e. /usr/share/php/i18nHTML/).  The i18nhtml.php file
+subdirectory "i18nHTML/" of a directory listed in the "include_path"
+from php.ini (i.e. /usr/share/php/i18nHTML/).  The "i18nhtml.php" file
 should be included in internationalized webpages using PHP's
-"include()" function.  The i18nhtml_config.php file should be edited
-to configure the installation.  In particular, the file specifies the
-database access method.  You need to configure the MySQL database like
-this:
+"include_once()" function.  The "i18nhtml_config.php" file should be
+edited to configure the installation.  In particular, the file
+specifies the database access method.  You need to configure the MySQL
+database like this:
 
 $ mysql -u root -p 
 CREATE DATABASE translation;
-GRANT select,insert,update,delete,create,alter,drop
+GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,ALTER,DROP
      ON translation.* TO address@hidden;
 SET PASSWORD FOR address@hidden('pass');
 FLUSH PRIVILEGES;
 
 
 You should copy the files from the "src/admin/" directory to some
-directory that exposed by apache to users that are allowed to provide
+directory that exposed by Apache to users that are allowed to provide
 translations.  This could be a normal public directory
 (http://yourwebserver.org/i18nHTML/) or a directory protected by
 access permissions in order to limit access to authorized users
 (i.e. https://yourwebserver.com/internal/i18nHTML/).  Regardless, you
-must specify the respective base-URL in the i18nhtml_config.php
-configuration file.
+must specify the respective base-URL in the "i18nhtml_config.php"
+configuration file.  At this point, you should also select a password
+for the administrator and put it into the configuration file.
 
-examples/ contains some example pages that use i18nHTML.  You do
-not need to install those pages.  The update*.php scripts in the
-src/ directory can be used to migrate databases from previous
-i18nHTML versions.  They do not need to be installed either.
+The update*.php scripts in the "src/" directory can be used to migrate
+databases from previous i18nHTML versions.  Make the respective
+script(s) briefly available on your webpage and access them with a
+browser to run the update.  You should then remove them from public
+access.  They do not need to be used if you are not updating from
+a previous i18nHTML version.
 
-doc/ should contain some additional documentation and examples
-how to use the system.  See also the i18nHTML-docs CVS repository
-for how the i18nHTML webpage itself is done.
+Next you should access the i18nHTML table generation page (table.php)
+(at http://yourwebserver.org/i18nHTML/table.php).  This will setup
+tables (additional tables if you are updating, all tables if this is a
+fresh installation) and create the administrative accounts.
+Afterwards you should be able to sign into the main administrative
+page (at http://yourwebserver.org/i18nHTML/index.html) using the
+"root" account and the password from the configuration file (do not
+use the MySQL password but the "sqlAdminPass" password).  At this
+point, you could remove the CREATE, ALTER and DROP priviledges from
+the i18nHTML user (if you are concerned about tight access
+permissions).
 
-On first start, i18nHTML should create MySQL tables.  They should
-look like this:
-mysql> explain map;
-+-------------+------------------+------+-----+---------+-------+
-| Field       | Type             | Null | Key | Default | Extra |
-+-------------+------------------+------+-----+---------+-------+
-| name        | blob             |      | MUL |         |       |
-| lang        | tinyblob         |      | MUL |         |       |
-| translation | blob             |      | MUL |         |       |
-| ranking     | int(10) unsigned |      | MUL | 0       |       |
-| IP          | tinytext         |      |     |         |       |
-+-------------+------------------+------+-----+---------+-------+
-5 rows in set (0.03 sec)
+You should now be able to administer the page using the "root"
+account.  The main functions are adding target translation languages,
+granting higher-level access to translators and deleting invalid
+translations.  The level of an account allows a translator to delete
+translations of lower-level translators.  Anyone (with access to the
+administrative page) initially starts at level zero.  All user
+accounts are tied to a particular language (except for the
+administrator's account).  Users with level X priviledges can grant
+level X-1 priviledges to other users of the same language.
 
-mysql> explain pending;
-+-------+---------+------+-----+---------+-------+
-| Field | Type    | Null | Key | Default | Extra |
-+-------+---------+------+-----+---------+-------+
-| c     | blob    | YES  | MUL | NULL    |       |
-| lang  | blob    | YES  | MUL | NULL    |       |
-| count | int(11) | YES  | MUL | NULL    |       |
-+-------+---------+------+-----+---------+-------+
-3 rows in set (0.00 sec)
+The source IP is logged for each person providing a translation, so it
+should be possible to trace mischief.  Unless accounts have been
+compromised, the user ID associated with each translation should make
+it trivial to delete translations from malicious users in bulk.  
+The administrative interface also features the "dig" pages that can
+help dig for obviously invalid translations.
 
-After CREATEing these tables, the script still
-needs INSERT, UPDATE, DELETE and SELECT permissions.
-DELETE is only required for the 'pending' table.
 
-The pending table is where untranslated text is placed when first
-encountered.  Any further encounters will increment the 'count'
-field within the matching row of the pending table.  The mass
-edit page (editor.php) will display the strings to translate
-in order from highest count to lowest.  This should enable
-translators to spend their time on the remaining untranslated
-entries most likely to be read.
+INTERNALS:
+==========
 
-The language bar generated will only show languages where at
-least one string is translated.  You can force additional
-languages by accessing the page with your default browser
-language set to one other than English (the assumed original
-language) and translating at least one string; manually
-specifying a language on the URL and translating at least one
-string; or viewing the index.php script and translating at
-least one string on each mass translate page for desired
-languages.
+The "pending" table is where untranslated text is placed when first
+encountered.  Any further encounters will increment the 'count' field
+within the matching row of the pending table.  The mass edit page
+("editor.php") will display the strings to translate in order from
+highest count to lowest.  This should enable translators to spend
+their time on the remaining untranslated entries most likely to be
+read.
 
-When translating a given string, all unique translations are
-stored in the database.  The translate.php page (the page
-shown during translation) will list all current translations.
+The "accounts" table stores account information.
 
-Warning: Although valid translations should be preserved,
-a malicious person can easily force all translations to refer
-to invalid or otherwise unwanted text.  Please back up your
-tables regulary and keep an eye out for irregular activity.
-The source IP is logged for each person providing a translation,
-so it should be reasonably easy to delete malicious translations
-if somebody decides to be nasty.
+All translations are stored in the "map" table.
 
-
-You may now want to open the "examples/start.php" page.  This page
-contains the description for your end-users on how to translate the
-pages using i18nHTML.  After opening start.php the tables have been
-created and you can populate the database with an initial set of
-translations:
-
-$ mysql -ui18nHTML -ppass < contrib/populate.sql
-
-That should be it.  Refresh the "start.php" page to see if
-you got a few languages to start out with :-).
+A list of languages that have been approved for translation is stored
+in the "languages" table.  The "do_def" field for languages is
+intended for a future extension of i18nHTML.  For now, it should be
+set for languages using the latin alphabet.

Modified: i18nHTML/src/examples/example.php
===================================================================
--- i18nHTML/src/examples/example.php   2007-01-06 08:32:34 UTC (rev 4209)
+++ i18nHTML/src/examples/example.php   2007-01-06 08:59:34 UTC (rev 4210)
@@ -1,5 +1,5 @@
 <?php
-include("i18nHTML/i18nhtml.php");
+include_once("i18nHTML/i18nhtml.php");
 DOCTYPE("HTML");
 echo "<html><head>";
 TITLE("Example page");
@@ -14,7 +14,7 @@
 W("A sentence with a %s that CAN be translated.",
   extlink_("http://gnunet.org/i18nHTML/";, "link text"));
 W("A %s to another translatable page.",
-  intlink_("http://gnunet.org/i18nHTML/index";, "link")); // .php is added 
automatically!
+  intlink_("http://gnunet.org/i18nHTML/index.php";, "link")); 
 BR(); // <br>
 echo W_("A function returning the translation.");
 W("For more functions, look into i18nhtml.inc.");

Modified: i18nHTML/src/examples/example2.php
===================================================================
--- i18nHTML/src/examples/example2.php  2007-01-06 08:32:34 UTC (rev 4209)
+++ i18nHTML/src/examples/example2.php  2007-01-06 08:59:34 UTC (rev 4210)
@@ -1,5 +1,5 @@
 <?php
-include("i18nHTML/i18nhtml.php");  // do this 1st, add translation support
+include_once("i18nHTML/i18nhtml.php");  // do this 1st, add translation support
 DOCTYPE("HTML","Transitional");         // tell the user agent document format
 setTranslateLinkMarker("***");          // make translation marker more visible
 editOnlyUntranslatedText();             // restrict translations to 
untranslated strings
@@ -42,16 +42,16 @@
 W("A sentence with a %s that CAN be translated.",
   extlink_("http://gnunet.org/i18nHTML/";, "link text"));
 W("A %s to another translatable page.",
-  intlink_("http://gnunet.org/i18nHTML/index";, "link")); // .php is added 
automatically!
+  intlink_("http://gnunet.org/i18nHTML/index.php";, "link"));
 BR(); // <br>
 echo W_("A function returning the translation.");
 W("For more functions, look into i18nhtml.inc.");
 P();
 
 HR();
-$t = "Notice how we don't have to escape or quote(\") ampersands & nor other";
-$t = $t . "HTML entities.  <<<--->>> and such even work. This looks like 
&amp;\n";
-W($t);
+$tt = "Notice how we don't have to escape or quote(\") ampersands & nor other";
+$tt = $tt . "HTML entities.  <<<--->>> and such even work. This looks like 
&amp;\n";
+W($tt);
 HR();
 
 P();

Modified: i18nHTML/src/examples/start.php
===================================================================
--- i18nHTML/src/examples/start.php     2007-01-06 08:32:34 UTC (rev 4209)
+++ i18nHTML/src/examples/start.php     2007-01-06 08:59:34 UTC (rev 4210)
@@ -11,19 +11,19 @@
   extlink_("http://gnunet.org/i18nHTML/";, "i18nHTML"));
 W("Please feel encouraged to help, for example by translating some of the 
pages to your native language.");
 W("Just view the pages in your language and click on the &quot;*&quot; after a 
sentence to translate it.");
-W("You can start a new language by adding <tt>lang=LANGUAGE</tt> after the 
<tt>.php3</tt> in the URL.");
-W("The translations incorporate a voting system, the highest ranked 
translation is displayed.");
-W($i18nHTMLsrcLang . " is always the source language.");
-W("Only developers can change the source, contact them if you find problems.");
-W("On the translation page, you find all other translations.");
-W("You can also vote for a specific translation by clicking on the respective 
sentence.");
-W("You are allowed to vote multiple times for the same sentence, e.g. to 
express strong feelings. :-)");
-W("The system logs your IP and allows the administrator to easily undo all 
operations that were performed from a certain IP address.");
+W("The system administrator can add additional languages, contact %s if you 
are interested in translating into a language that is not yet listed.", 
+  "address@hidden");
+W("%s is the source language on this system.",
+  $i18nHTMLsrcLang);
+W("This version of i18nHTML requires translators to register (but your e-mail 
address is only used to send the password and not stored in the database).");
+W("This registration step is used to guard the system against abuse.");
+W("Each registered account only works for translations into the language 
specified during registration.");
+W("The administrator can designate trusted users which can delete translations 
(for their target language).");
+W("The system logs your IP and allows the administrator to easily delete all 
translations provided by a particular user.");
 if ($lang != $i18nHTMLsrcLang) {
   W("You can translate the most commonly requested untranslated sentences for 
your language using the %s.",
     intlink_("editor.php", "mass translation page"));
 }
-
 generateFooter();
 echo "</body></html>\n";
 ?>

Modified: i18nHTML/todo
===================================================================
--- i18nHTML/todo       2007-01-06 08:32:34 UTC (rev 4209)
+++ i18nHTML/todo       2007-01-06 08:59:34 UTC (rev 4210)
@@ -1,13 +1,15 @@
 Ideas for future development (with priority):
 
 Users:
-* expand on-line documentation [MED]
+* update on-line documentation [MED]
 * enable users to view & edit their own translations
 
+Administration:
+* enable default translation feature
+
 Installation:
 * finish debian package:
   - automatically setup mysql database
   - automatically install apache configuration file
   - restart apache2
-* create script for gathering of initial set of translations [MED]