KnowledgeTree Internationalisation (i18n)
-----------------------------------------

Overview
--------
Support for i18n has been added to the KnowledgeTree (except for images), and
KnowledgeTree is ready to accept translations.  This is a mammoth task that
will require the support and aid of the KnowledgeTree community :)

Jam Warehouse can assist organisations in getting or keeping KnowledgeTree
translated into a language, please contact them at
kt-questions@jamwarehouse.com if that is of interest.

Requirements
------------

i18n requires gettext (http://www.gnu.org/software/gettext) and the gettext php module to work
(see http://php.net/gettext for installation instructions).

Completed Tasks and Implementation Details
------------------------------------------

- i18n/<locale>/LC_MESSAGES/knowledgeTree.mo
							knowledgeTree.po
			   /graphics
			   
- gettext support loaded if php module available

- all active (ie, not disabled) content in documents marked up

- checks the browser's Accept-Language header and uses that language (if there is a translation for it)

The TODO List
-------------

Images have not yet been done.


Guidelines
----------

Here are some guidelines for adding gettext support to the KnowledgeTree.

- find translatable strings and wrap literals with _() eg. 
	original:
    $sToRender .= "\t\t\t\t<th class=\"sectionHeading\" colspan=\"2\"><font color=\"ffffff\">Pending Web Documents</font></th>\n";		
	i18n'd:
    $sToRender .= "\t\t\t\t<th class=\"sectionHeading\" colspan=\"2\"><font color=\"ffffff\">" . _("Pending Web Documents") . "</font></th>\n";			

- if strings are concatenated with dynamic content use sprintf eg.
	original:	
    $sToRender .= "\t\t<td>Hi " . $sUserName . ", welcome back to the " . lookupField($default->organisations_table, "name", "id", $default->organisationID) . 
    			  "DMS, part of the Knowledge Tree</td>\n";	
	i18n'd:
    $sToRender .= "\t\t<td>" . sprintf(_('Hi %s, welcome back to the %s DMS, part of the Knowledge Tree'), 
    									$sUserName, 
    									lookupField($default->organisations_table, "name", "id", $default->organisationID)) . 
    			   "</td>\n";

- images- use the imgSrc function to dynamically use the images in the i18n directory (if they exist) eg.
	original:
    $sToRender .= "\t\t<td><img src=\"$default->graphicsUrl/welcome.gif\" border=\"0\"/></td>\n";		
	i18n'd:
    $sToRender .= "\t\t<td><img src=\"" . imgSrc("welcome.gif") . "\" border=\"0\"/></td>\n";	

Images to translate
-------------------
heading.gif: Document Management System
welcome.gif: Welcome to the Knowledge Tree
search.gif: SEARCH
tree.gif: KnowledgeTree (no translate?)

admin/over.gif: ADMIN
admin/norm.gif: ADMIN
asearch/over.gif: ADVANCED SEARCH
asearch/norm.gif: ADVANCED SEARCH
help/over.gif: HELP
help/norm.gif: HELP
home/over.gif: DASHBOARD
home/norm.gif: DASHBOARD
leftnav/links.gif: Links
leftnav/uadmin.gif: Contact Unit Admin
leftnav/cadmin.gif: Contact Admin
logout/over.gif: LOGOUT
logout/norm.gif: LOGOUT
mdocs/over.gif: BROWSE COLLECTION
mdocs/norm.gif: BROWSE COLLECTION
prefs/over.gif: PREFERENCES
prefs/norm.gif: PREFERENCES
subscriptions/over.gif: SUBSCRIPTIONS
subscriptions/norm.gif: SUBSCRIPTIONS

widgets/docactions/archive.gif: ARCHIVE
widgets/docactions/disabled-archive.gif: ARCHIVE
widgets/docactions/checkin.gif: CHECK-IN
widgets/docactions/disabled-checkin.gif: CHECK-IN
widgets/docactions/checkout.gif: CHECK-OUT
widgets/docactions/disabled-checkout.gif: CHECK-OUT
widgets/docactions/delete.gif: DELETE
widgets/docactions/disabled-delete.gif: DELETE
widgets/docactions/dependentdoc.gif: LINK NEW DOC
widgets/docactions/disabled-dependentdoc.gif: LINK NEW DOC
widgets/docactions/discussion.gif: DISCUSSION
widgets/docactions/disabled-discussion.gif: DISCUSSION
widgets/docactions/download.gif: DOWNLOAD
widgets/docactions/disabled-download.gif: DOWNLOAD
widgets/docactions/email.gif: EMAIL
widgets/docactions/disabled-email.gif: EMAIL
widgets/docactions/history.gif: HISTORY
widgets/docactions/disabled-history.gif: HISTORY
widgets/docactions/move.gif: MOVE
widgets/docactions/disabled-move.gif: MOVE
widgets/docactions/publish.gif: PUBLISH
widgets/docactions/disabled-publish.gif: PUBLISH
widgets/docactions/subscribe.gif: SUBSCRIBE
widgets/docactions/disabled-subscribe.gif: SUBSCRIBE
widgets/docactions/unsubscribe.gif: UNSUBSCRIBE
widgets/docactions/disabled-unsubscribe.gif: UNSUBSCRIBE
widgets/docactions/view.gif: VIEW
widgets/docactions/disabled-view.gif: VIEW


	
Testing
-------
- install gettext command line utilities
- run xgettext to generate .po files eg.
Neil quite likes:
  $ find . -type f | xgettext --no-wrap -d knowledgeTree -L PHP -s -f - -o i18n/knowledgeTree.po

Michael was using:
  xgettext --files-from=i18n/file-list -LPHP --keyword=_ --no-wrap --msgid-bugs-address="kt-i18n@jamwarehouse.com" -o knowledgeTree.po

- write a test translation by editing the po file appropriately.  if you have problems with the order of parameters, because your language's
  ordering is different then in english. You can use the $ to change order eg: 
        msgid "Upgrading item %d of %d"
        msgstr "... %2$d ... %1$d ..."
- construct the right directory structure inside i18n eg.
  $ mkdir -p i18n/es/LC_MESSAGES/	        
- upgrade the existing .po files in each translation using:
  $ mv knowledgeTree.po old.po
  $ msgmerge --no-wrap old.po ../knowledgeTree.po --output-file=knowledgeTree.po
  $ rm old.po
- use msgfmt to compile your translated .po file to a .mo
  $ msgfmt --check $knowldgeTree.po --output-file=i18n/$es/LC_MESSAGES/knowledgeTree.mo
- change $default->defaultLanguage in config/environment.php and verify your translation.

$Id$