--- manual-doc_core_inside-27-09-2005_17-13-48.txt 2006-07-26 17:23:30.000000000 +0200 +++ manual-doc_core_inside_4-0-0.txt 2006-07-26 18:34:12.000000000 +0200 @@ -7,7 +7,7 @@ Inside TYPO3 Extension Key: doc_core_inside -Copyright 2000-2005, Kasper Skårhųj, +Copyright 2000-2006, Kasper Skårhųj, This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml @@ -15,7 +15,7 @@ The content of this document is related to TYPO3 - a GNU/GPL CMS/Framework available from www.typo3.com -Revised for TYPO3 3.7 +Revised for TYPO3 4.0 Table of Contents Table of Contents Inside TYPO31 @@ -117,7 +123,8 @@ The goal is to take you "under the hood" of TYPO3. To make the principles and opportunities clear and less mysterious. To educate you to help continue the development of TYPO3 along the already established lines so we will have a consistent CMS application in a future as well. And hopefully my teaching on the deep technical level will enable you to educate others higher up in the "hierarchy". Please consider that as well!Up-to-date information? We are committed to keeping this document up-to-date. We also want this document and related documents to contain enough information for you to develop with TYPO3 effectively. But guess what - in any case the source is updated before this document is and therefore the ultimate source of both up-to-date information and more information is peeking into the source scripts! And for the source scripts we are also trying to keep them well documented. So generally the source code is the final authority, the final place to look for features and get a precise picture of function arguments etc. The documentation inside the source scripts will be short and precise, no examples, not much explanation. But enough for people knowing what to look for. This document - an other documents like "TYPO3 Core API" - should provide the greater picture explanations for use. -If you find that sections in this document are missing something, please help the author by notifying him and possibly supply a piece of text which could serve as the supplement you want to have added. You can also use the annotation feature in the online version at TYPO3.org.A basic installation +If you find that sections in this document are missing something, please help the author by notifying him and possibly supply a piece of text which could serve as the supplement you want to have added. You can also use the annotation feature in the online version at TYPO3.org. +Notice: TYPO3 version 4 bears a new visual interface (skin) that is not reflected in the screenshots of this document. However, this does not have any impact on the content itself.A basic installation Since we are dealing with the core of TYPO3 it might help us to make a totally trimmed down installation of TYPO3 with only the core - then we can see what is actually left... First of all the general introduction to the source code file structure is found in the "Installing and Upgrading" document. So I?ll not be going into details on that here. For the coming sections in this document I have made a directory "coreinstall" on the same level as an installation of the source code. The "coreinstall" directory is going to be the base directory of the installation (this path is internally in TYPO3 known as the constant "PATH_site"). This is where the website would run from normally. @@ -180,14 +187,12 @@ # mkdir uploads/ ... and all is fine.Basic Core Installation Summary -So lets sum up what we have now:File structure: -This is the directory structure partly expanded: - - - -And here follows an explanation of the main directories of interest +So lets sum up what we have now:File structure +These are the main directories of interest: Directory Content +t3lib/ +TYPO3 libraries and core database setup (t3lib/stddb/) typo3/ (shared between all websites) @@ -200,9 +205,7 @@ The difference is that global extensions might be missing from the distributed source code (meant to be updated by the EM) while the system extensions are "permanent" and will always be a part of the distributed source. Further you cannot update the system extensions unless you set a certain configuration flag in TYPO3_CONF_VARS NOTE: In case you want to allow the Extension Manager to update global and system extensions you must also allow writing to "ext/" and "sysext/". Install Tool will warn you. gfx/ -Various graphical elements. (Is a symlink to t3lib/gfx/) -t3lib/ -TYPO3 libraries and core database setup (t3lib/stddb/) +Various graphical elements install/ Contains the Install Tool starter-script. Basically this is an index.php-script which initializes a constant that - if defined - will launch the Install Tool. NOTE: Make sure to properly secure access to the Install Tool! @@ -232,7 +235,8 @@ Also used by default for images inserted into the RTE. Basically we completed these steps to create the files and folders of a bare-bone TYPO3 core installation: -Create symlink to backend administration directory, typo3/ (shared) +Create symlink to the t3lib/ directory (shared) +Create symlink to the backend administration directory, typo3/ (shared) Create directories typo3conf/, uploads/, typo3temp/ (specific) Create typo3conf/localconf.php file and add a minimum of configuration to get started. (specific)Notice on temp_CACHED-files in typo3conf/ There are two (sometimes more) files which we didn?t create ourselves; the cached "temp_CACHED_xxxxxx_ext_localconf.php" and "temp_CACHED_xxxxxx_ext_tables.php". These two files are automatically compiled from the currently loaded extensions and written to disk. If you look into the files you can see that they are just scripts automatically collected from the loaded extensions, then concatenated and written to disk. This concept improves parsing a lot since it make it possible to include one file (the cached file) instead of maybe 50 files from different locations. @@ -1221,7 +1225,7 @@ The "locallang" file reference in line 2 points to a "locallang"-file which in this case looks like this: Array (         ?title? => ?Advanced functions?, @@ -1476,7 +1480,7 @@ 10: 11:     // Defining PATH_thisScript here: Must be the ABSOLUTE path of this script in the right context: 12:     // This will work as long as the script is called by it?s absolute path! -13: define(PATH_thisScript, $_ENV[?_?] ? $_ENV[?_?] : $_SERVER[?_?]); +13: define("PATH_thisScript", $_ENV[?_?] ? $_ENV[?_?] : $_SERVER[?_?]); 14: 15:     // Include configuration file: 16: require(dirname(PATH_thisScript).?/conf.php?); @@ -1598,51 +1602,378 @@ tx_templavoila_pito int(11) DEFAULT ?0? NOT NULL ); The upgrade process -More information about the process of upgrading TYPO3 can be found in the document "Installing and Upgrading TYPO3".LocalizationStrategy -Internationalization (i18n) and localization (l10n) issues are handled by the "language" class included my the "template.php" file and instantiated as the global variable $LANG in the backend. -The strategy of localization in TYPO3 is to translate all the parts of the TYPO3 Backend (TBE) interface which are available to everyday users of the CMS such as content editors, contributors, and to a certain extend, administrators. However all developer/admin-parts should remain in English. -The reason for keeping the adminstrator/developer parts in English is that those parts change and expand too quickly. Further it would be a huge task to both implement and translate. And the most important reason is that we want to keep a common vocabulary between developers in the international TYPO3 developer community. So in fact there are strong reasons for not translating the whole system into local languages!How translations are handled by the system -The default language of TYPO3 is English. -First of all the list of available system languages is defined in the constant TYPO3_languages (hardcoded/defined in config_default.php). At the time of this writing the value of the TYPO3_languages constant is: ?default|dk|de|no|it|fr|es|nl|cz|pl|si|fi|tr|se|pt|ru|ro|ch|sk|lt|is|hr|hu|gl|th|gr|hk|eu|bg|br|et|ar|he|ua|lv|jp|vn?. This "list" is two-char identification codes representing languages. The code usually reflects a ccTLD related to the language but doesn?t have to as long as it is unique. -Then the extension "lang" found in the folder typo3/sysext/lang/ contains all translations for the main system parts. Those translations are all found as "locallang" files; See below for details. -The "language" class (from sysext/lang/lang.php) further contains an instance of the class "t3lib_cs" where the charsets used for each language are defined. The charset is detected by the "template" class and automatically set for the documents in the backend. -Translation of "locallang" files is handled on typo3.org by a dedicated interface for this task. Since the concept of "locallang" files are used everywhere and in individual extensions this is the perfect way to handle translation of the system. There are two strands of locallang files: -"locallang*.php" files; They contain the $LOCAL_LANG array in a PHP script which is simply included. Extensions with locallang*.php files are uploaded to TER, then translated by the team of translators, then downloaded again after the translations has been applied. See this page for more information. -"locallang-XML" files; They are XML files containing a structure similar to $LOCAL_LANG but a lot of meta data in addition. They are translated by a backend tool inside TYPO3 (extension "llxmltranslate"). They are the preferred file format for translations in most cases.Character sets -Currently, local charsets are used by default inside TYPO3. However it is highly recommended to set $TYPO3_CONF_VARS[?BE?][?forceCharset?] = "utf-8" which will force the backend to run in utf-8 regardless of "native" charset. Forcing the charset to "utf-8" also means that all content in the database will be managed in "utf-8" and you might corrupt existing data if you set it after having added content in another charset."locallang" files -Anywhere in the source code where files prefixed "locallang*.php" are found they are supposed to contain only a $LOCAL_LANG array with translations and formatted exactly like the examples below. These files are recognized by the typo3.org translation tool. Further they allow to group related labels together and only load relevant labels into memory as they are needed. -A "locallang" file looks like this (sysext/lang/locallang_tca.php): - Array (        ?pages? => ?Page?,        ?doktype.I.0? => ?Standard?,        ?doktype.I.1? => ?SysFolder?,        ?doktype.I.2? => ?Recycler?,        ?title? => ?Pagetitle:?,        ?php_tree_stop? => ?Stop page tree:?,        ?is_siteroot? => ?Is root of website:?,        ?storage_pid? => ?General Record Storage page:?,        ?be_users? => ?Backend user?,        ?be_groups? => ?Backend usergroup?,        ?sys_filemounts? => ?Filemount?,    ),    ?dk? => Array (        ?pages? => ?Side?,        ?doktype.I.0? => ?Standard?,        ?doktype.I.1? => ?SysFolder?,        ?doktype.I.2? => ?Papirkurv?,        ?title? => ?Sidetitel:?,        ?php_tree_stop? => ?Stop sidetrę:?,        ?is_siteroot? => ?Siden er websitets rod:?,        ?storage_pid? => ?Generel elementlager-side:?,        ?be_users? => ?Opdaterings bruger?,        ?be_groups? => ?Opdaterings brugergruppe?,        ?sys_filemounts? => ?Filmount?,    ),    ?de? => Array (        ?pages? => ?Seite?,        ?doktype.I.0? => ?Standard?,        ?doktype.I.1? => ?SysOrdner?,        ?doktype.I.2? => ?Papierkorb?,        ?title? => ?Seitentitel:?,        ?php_tree_stop? => ?Seitenbaum stoppen:?,        ?is_siteroot? => ?Ist Anfang der Webseite:?,        ?storage_pid? => ?Allgemeine Datensatzsammlung:?,        ?be_users? => ?Backend Benutzer?,        ?be_groups? => ?Backend Benutzergruppe?,        ?sys_filemounts? => ?Dateifreigaben?,    ), -....[lots of other languages defined]... +More information about the process of upgrading TYPO3 can be found in the document "Installing and Upgrading TYPO3".Versioning and WorkspacesVersioning in TYPO3 +TYPO3 offers versioning of the database elements it manages. This versioning system allows you to work on future versions of content without affecting the live content. It is used by workflow systems to offer a process for such content, going from creation, editing to review and publishing (where the draft version is swapped with the live version). +Versioning is available in the core API by default, but to gain access to management tools you must install an extension, eg. the system extension versioning. +The versioning system offers three types of versioning fitting various scenarios: +Element: A single database record from any table with versioning enabled is copied and configured as a future version of the original element. Color code is light green. +Page: A single page record is versioned and other content on the page (tables with versioning_followPages set in [ctrl]) is copied along. Color code is light blue. +Branch: A single page record is versioned and subpages to a specified depth including content is copied along. Color code is light red. +Here are some explanation why three types are necessary to gain the most flexibility: +Element versions are the most basic form and also the simplest. Whenever possible I would prefer this type because of the simplicity. However Element versions cannot take their environment into account. So moving an Element version to another page or even within the same page is impossible (or so complex to implement that we didn?t even try). +Unfortunately, changing the order of for example content elements on a page is a very common way to re-organize page content. Therefore the versioning type Page means that some page content is copied along with the page version and thereby freely re-arrangeable. Furthermore, the process of versioning is necessary only one time for the page and not for each element on it that is changed. The downside to this method is that more content than necessary is copied and when the page versions are swapped, the new content elements on the page will have different UIDs than the former (breaking all links with anchors or Insert Record/TemplaVoila references to content elements on the former page ). The Page versioning type is most useful for columns-based websites, while TemplaVoila based sites can benefit more from the element-based versioning, especially in the context of workspaces where versioning is transparently done. +Finally, the Branch versioning type is used if you want to rework a whole branch of the page tree of a site. This gives you flexibility in terms of adding, deleting, moving and copying elements around that is unmatched by any of the other types. But on the other hand you suffer the same problems of Page versioning where you might break links and other id-references since all content below the versioned page root point will be separate copies of original content without any references back to their originals. You will loose not only anchor-point references but also links to page IDs! As it is right now I consider this type most useful for building new sections of a website or major rearrangements of sections where these consequences are acceptable. Yet, it remains to be seen what actual usage people will make of it.Technical details +Versioning must be enabled on a per-table basis in the [ctrl] section of the $TCA array entry for a table. In addition a fixed set of fields has to exist for the management of versions. All of these technical details are specified in the document TYPO3 Core API where you will also find other in-depth information. +Future and past versions of records in TYPO3 remain in the same table as the live version. However, all offline versions will have a pid value of -1 which identifies them as offline. Further they have a field, t3ver_oid which points to their live (online) version. +When a future/past version is swapped with the live version it is done by swapping all field values except the uid and pid fields (and of course versioning related fields are manipulated according to their function). It means that online content is always identified by the same id as before and therefore all references are kept intact (except content inside Page and Branch versioning, see above). +Versioning is easy for existing elements. However, creating and deleting poses other problems. This is solved the following way: +Deleting elements is done by actually creating a new version of the element and setting a flag in the new version (t3ver_state=2) that indicates the live element must be deleted upon swapping the versions. Thus deletion is scheduled to happen when the versions are swapped. +Creating elements is done by first creating a placeholder element which is in fact live but carrying a flag (t3ver_state=1) that makes it invisible online. Then a new version of this placeholder is made which is what is modified until published.Unique fields +Unique fields like a page alias or user name are tricky in a versioning scenario because the publication process must perform a check if the field is unique in the Live situation. The implications of implementing this means that we have chosen a solution where unique fields are simply not swapped at all! It means that publication of a new version of a page cannot and will not alter the alias of the live version. The Live unique value will remain until changed in the live version. +You can hide fields with the unique keyword when they are offline versions. This is done with the display condition: +?displayCond? => ?VERSION:IS:false?,Life cycle +When a new version of an element is created, its publishing counter (t3ver_count) is set to zero. This means its life cycle state is interpreted as Draft; the element is in the pipeline to be published. When the element is published the life cycle state is Live and when it is swapped out again the publishing counter will be incremented and the life cycle is interpreted as Archive. Yet, the element can be continously published and unpublished and for each time the publishing counter will be incremented, telling how many times an element has been online.Permissions +This is an overview of how permissions are handled in relation to versioning: +Display +Read permissions are evaluated based on the live version of pages (as the basic rule). The read permissions of the offline page version in a workspace is not observed. (Reason: When for example the page tree is generated TYPO3 selects all live records and then looks for versioned overlays). +Read permissions for new page versions of branch type is observed in eg. Web > List module. This is due to the fact that the real ID of a branch type page is what the backend uses in the Web>List module while for page and Element type versions the ID of the live record is used in which case the live records display-permissions is what gets evaluated. +Versionizing records +To create a new version the user must have read permission to the live record he requests to version +A new version of a page will inherit the owner user, group and permission settings from the live record +To create a "Page" or "Branch" version of a page requires read permission to all subpages. All records that should be copied along with "Page" and "Branch" versions will be so regardless of the users table-modify permissions. +Publishing version +To publish, a user must have general publishing permission in the workspace, for instance be the owner of it or have access to the Live workspace. +In addition, the user must have read and edit access to the offline version being published plus edit access to the live version that a publishing action will substitute! +The permissions of a new version of a page follows the page when published. +Editing records +For all editing it is required that the stage of the versioned record (or root point) allows editing. +Page records: +Permission to edit is always evaluated based on the pages own permission settings and not the live records. +Records from non-pages tables: +"Element" versions: Always based on the live parent page. +Live records inside a "Branch" or "Page" versioning type immediately under the root point depends on permissions of the root point offline version. +New records +When new records are created with a version and live place holder the permissions depend on the live page under which the record is created. +Moving records +Records that are related to "Page" and "Branch" versions of a page can be moved internally or to other "Page" or "Branch" versions as long as the source and destination root points has a stage that allows it. +New records created with a place holder element can be moved freely around except into other "Page" and "Branch" versions. +Generally, the stage of a moved record has to allow for editing plus regular permissions for moving are observed. +Deleting records +If the record is inside a "Page" or "Branch" type version of a page, then it can be readily deleted if other permissions allow, including stage of the root point. +If a record is outside a versioned branch and supports versioning it will be marked for deletion if all usual requirements are fulfilled at the time of the delete request: Delete access to record, that no subpages are found if not recursive deletion is enabled and no disallowed table records are found. As soon as the record is marked for deletion any change to the record and subpages that would otherwise prevent deletion for the user will not be effective: The record will be deleted upon publication! +If you try to delete a Live record for which a version is found in the workspace, that version is deleted instead. +Detaching versions from a workspace and raising stage of versions can be done as long as the user has edit permission to the record. +WorkspacesProblems with versioning usability +One problem with raw versioning is that it easily requires a lot of administration and awareness from users. For instance, an author has to consciously create a new version of a page or content element before he must edit it. Maybe he forgets. So either he makes a change live or - if TYPO3 is configured for it - he will be denied access to editing but frustrated over an error message. Further, keeping track of versions across the system might be difficult since changes are often made at various places and should be published together. +Some of these problems are fixed when elements are always processed with a workflow that keeps track of them. But a workflow process might be too rigid for scenarios where a group of editors are concerned with the site content broadly and not the narrow scope of an element centred workflow. +Furthermore, the preview of future content is hard to implement unless you require people to request a preview of each individual new version - but most often they like to see the combined impact of all future versions!The perfect solution +The concept of workspaces is the answer. Workspaces puts versioning into action in a very usable and transparent way offering all the flexibility from live editing but without sacrificing the important control of content publishing and review. +A workspace is a state in the backend of TYPO3. Basically there are three types of workspaces: +LIVE workspace: This is exactly the state TYPO3 has always been in. Any change you make will be instantly live. Nothing has changed, it just got a name. +Draft workspace: When a user selects the draft workspace new rules apply to anything he does in the backend: +Draft: Any change he tries to make will not affect the live website. It?s a safe playground. +Transparent versioning: He can edit pages and elements because a new version is made automatically and attached to the workspace. No training needed, no administrative overhead! +Previewing: Visiting the frontend website will display it as it will appear when all versions in the workspace is eventually published (switch enable/disable this feature). +Overview of changes: The workspace manager module gives a clear overview of all changes that has been made inside the workspace across the site. This gives unparalleled control before publishing the content live. +Constraints: Only tables that support versioning can be edited. All management of files in fileadmin/ is disabled because they may affect the live website and thus would break the principle of safe playground. +Custom workspaces: +Inherits all properties of the default Draft workspace but can be configured additionally with owners, members and reviewers plus database- and file mounts plus other settings. A custom workspace is a great way to do team-based maintenance of (a section of) the website including a basic implementation of workflow states with editor-reviewer-publisher. +Some of the constraints of the default draft workspace can be eased up a bit by configuration; For instance records that does not support versioning can be allowed to be edited and file mounts can be defined inside of which files can be managed. -    ?sk? => Array (        ?pages? => ?Strįnka?,        ?doktype.I.0? => ?`tandardnį?,        ?doktype.I.1? => ?Systémovį zlo~ka?,        ?title? => ?Titulka strįnky?,    ),    ?lt? => Array (        ?pages? => ?Puslapis?,        ?doktype.I.0? => ?Standartinis?,        ?doktype.I.1? => ?Sisteminis Aplankas?,        ?doktype.I.2? => ?Šiukšlinė?,        ?title? => ?Puslapio antraštė:?,        ?php_tree_stop? => ?Stapdyti puslapio medį:?,        ?is_siteroot? => ?Ar svetainės šakninis:?,        ?storage_pid? => ?Bendra Puslapio Įrašo saugykla:?,        ?be_users? => ?Administravimo pusės vartotojas?,        ?be_groups? => ?Administravimo pusės vartotojo grupė?,        ?sys_filemounts? => ?Bylų stendas?,    ),);?> +A draft workspace is a container for draft versions of content. Each versionable element can have zero or 1 version in a workspace (versions are attached to workspaces with a relation in the field t3ver_wsid). The fact that there can be only one new version of any element in a draft workspace makes in unambiguous which version to edit, preview and publish. +Analogy: The concept of workspaces can be compared with how CVS works for programmers; You check out the current source to your local computer (= entering a draft workspace), then you can change any script you like on your local computer (= transparent editing in the workspace), run tests of the changed code scripts (= previewing the workspace in the frontend) , compare the changes you made with the source in CVS (= using the Workspace Manager modules overview to review the complete amount of changes made) and eventually you commit the changes to CVS (= publishing the content of the workspace).Publishing and swapping +There are two ways to publish an element in a workspace; publish or swap. In both cases the draft content is published live. But when swapping it means the current live element is attached to the workspace when taken offline. This is contrary to the publish mode which pushes the live item out of any workspace and into the archive. +The swapping mode is useful if you have a temporary campaign, say a christmas special frontpage and website section. You create the christmas edition in a custom workspace and two weeks before christmas you swap in the christmas edition. All normal pages and elements that were unpublished are now in the workspace, waiting for christmas to pass by and eventually the old frontpage etc. will be swapped back in. The christmas edition is now back in the workspace and ready for next year.More on Workspace types +I would like to more clearly describe the various workspace types, their differences and applications: +Topic +Live workspace +Draft workspace (default) +Custom workspaces +Access +Users and groups must be specifically allowed access to the Live workspace. +(Checkboxes in user/group record) -So the $LOCAL_LANG array has the syntax -$LOCAL_LANG[language_key][label_key] = ?label_value?; -Alternative locallang-syntax for large translation sets -As you can see all available languages are located in the same file! However if a set of labels is very large it is inefficient to load all languages into memory when you need only the default plus the current language to be available (eg. Danish). -Therefore you can split locallang files into a structure with a main file (locallang*.php) and sub-files (locallang*.[langkey].php). An example is sysext/lang/locallang_core.php: - Array (        "labels.openInNewWindow" => "Open in new window",        "labels.goBack" => "Go back",        "labels.makeShortcut" => "Create a shortcut to this page?",        "labels.lockedRecord" => "The user ?%s? began to edit this record %s ago.",        "cm.open" => "Open", -... [lot of more labels here].... -        "cm.save" => "Save",        "cm.unzip" => "Unzip",        "cm.info" => "Info",        "cm.createnew" => "Create new",    ),    ?dk? => "EXT",    ?de? => "EXT",    ?no? => "EXT",    ?it? => "EXT",    ?fr? => "EXT",    ?es? => "EXT",    ?nl? => "EXT",    ?cz? => "EXT",    ?pl? => "EXT",    ?si? => "EXT",    ?fi? => "EXT",    ?tr? => "EXT",    ?se? => "EXT",    ?pt? => "EXT",    ?ru? => "EXT",    ?ro? => "EXT",    ?ch? => "EXT",    ?sk? => "EXT",    ?lt? => "EXT",);?> +(For upgrades from pre-4.0 versions this is done by default). +Users and groups must be specifically allowed access to the Draft workspace. +(Checkboxes in user/group record) +Granted through the workspace configuration which includes: +- A list of editors (users and/or groups) +- A list of reviewers (users and/or groups) +- Owner users (initial creator) +Editing -The string token "EXT" set for all the other languages than "default" tells the "language" class that another file contains the language for this language key. For the Danish language this file would be "sysext/lang/locallang_core.dk.php": - "Åben i nyt vindue",            "labels.goBack" => "Gå tilbage",            "labels.makeShortcut" => "Opret genvej til denne side?",            "cm.open" => "Åbn",... [lot of more labels here].... -            "cm.save" => "Gem",            "cm.unzip" => "Unzip",            "cm.info" => "Info",            "cm.createnew" => "Opret ny",);?> +Live content +Draft versions of live content +Draft versions of live content -A requirement is that this "sub-file" sets only it?s own language key (here "dk") in the $LOCAL_LANG array. Thus simply including this file after the main file will add the whole "dk" key to the existing $LOCAL_LANG array with no need for array merging! -Notice another detail which is a general feature of $LOCAL_LANG arrays: The label key ?labels.lockedRecord? is not specified for the Danish translation. That simply means that the value of the "default" key (English) will be shown until that value will be added by the Danish translator!"locallang-XML" files -The locallang-XML files contains the same information as the PHP-based counterparts. In addition a lot of meta data used in the translation tool is included. -Performance is great with the XML files, might even be better than the native PHP files. This is because the content of the XML file is cached based on the modification time on the xml file. -"locallang-XML" files can also store the translations of a single language in external files. But the reason for doing so would be different than for locallang*.php files; With the PHP based files this was useful for performance reasons since you wouldn?t load all languages into memory at the same time. But since the XML files are cached (caching the default and current language labels in a temporary file inside typo3temp/) the files can be as large as you like and it will not affect the performance at all (unless on the first hit where cache files are generated of course - in which case the history shows it acquires large amounts of memory...). The main reason for using external files for locallang-XML should be distribution considerations; for instance CSH labels could consume very large amounts of space and multiplying that with the number of TYPO3 languages might totally bloat a file. So you might want to distribute a single translation in another file, possibly in another extension. -The format of locallang-XML files can look like this example: +Option: To allow editing of tables without versioning available. +DB mounts +From user profile +From user profile +Specific DB mounts can be specified in which case they will overrule DB mounts from user profiles. +Specific DB mounts are required to be within the DB mounts from the user profile (for security reasons) +If no DB mounts specified for workspace, user profile mounts are used (default) +File mounts +From user profile +None available. All file manipulation access is banned! (Otherwise violation of draft principle) +By default, none is available due to same principle as for Draft workspace. +Optionally, file mounts can be specified for convenience reasons. +Scheduled publishing +N/A +N/A +If CLI-script is configured in cronjob you can specify publishing date/time down to the minute. You can also specify an unpublish time which requires the use of swapping as publishing type. +Reviewing +Only through a separate workflow system. +Content can be raised from Editing stage through Review to Publish. +However, the state does not impose any limitations on editing and publication of workspace contents. +Members can raise content from Editing stage to Review. Members can only edit content when its in Editing stage (or Rejected) + +Reviewers can raise the content from Editing stage to Review stage to Publish - or they can reject content back to editing. Reviewers can only edit content in these modes. + +Owners can operate all states of course. Owners are the only ones to edit content when in Publish mode. Thus Publish mode provides protection for content awaiting publication. + +The Rejected flag is reset automatically when editing occurs on a rejected element. + +Options available for automatic email notification between the roles. +Publishing +(For all: Requires edit access to live element) +No limitations. Content can be edited live and even content from other workspaces can be published through the versioning API regardless of stage. +All users with access to Live workspace is able to publish. +Workspace owners can publish (even without access to Live workspace). +Reviewers/Members cannot publish unless they have access to online workspace as well (this default behaviour can be disabled). + +Option: Restrict publishing to elements in "Publish" stage only. +Settings +N/A +N/A +Users with permission to create a custom workspace can do so. +Workspace owners can add other owners, reviewers and editors and change all workspace properties. +Auto versioning +N/A +Yes +Yes, but can be disabled so a conscious versioning actions is required. +Swapping +N/A +Yes +Yes, but can be disabled. +Versioning types +All +All +All, but you can disable any of the types Element, Page and Branch. +Other notes + + +Custom workspaces has a freeze flag that will shut down any update/edit/copy/move/delete etc. command in the workspace until it is unset again. +Module access +All backend modules can specify $MCONF[?workspaces?] = [online,offline,custom] to limit access based current workspace of user. See description elsewhere in this document. +Usage +Administrative purposes. First creation of site. +Everyday maintenance for trusted editors. +Specific projects on a site branch. Simple review-cycles. Informal team-work on site maintenance. + +Generally, admin users have access to all functionality as usual.Supporting workspaces in extensions +Since workspaces implies transparent support all over the backend and frontend it means that extensions must be programmed with this in mind. Although the ideal is complete transparency in backend and perfect previews in the frontend this is almost impossible to obtain. But a high level of consistency can be obtained by using API functions in TYPO3. These functions and the challenges they are invented to answer are discussed in TYPO3 Core API.Using versioning and workspaces +This section shortly covers the workspace related features in the backend with a visual tour-de-force. +Most significantly workspaces have a selector box in the lower right corner of the backend. The shortcut frame is permanently visible for users unless disabled by Page TSconfig: + + +In this selector box the backend user chooses between the workspaces available to him. The whole backend reloads each time he changes workspace. This is necessary because the backend might be differently composed depending on the workspace the user is in. +The workspace is reflected in the top of the page tree: + + +By default the "Live" workspace is not, but this is easily configured with User TSconfig: "options.pageTree.onlineWorkspaceInfo = 1" + + +When you are in a draft workspace you will find a "New version" button in various modules, including Web > Page: + + +Clicking this button will create a new "Page" type version of the page. In the page tree "Page" type versions are highlighted with a blue background color. This means the page header is versioned and content elements on the page is copied along. (See previously for a description of this versioning type). This type of versioning offers the flexibility to rearrange content elements between the columns of a page. + + +The module Web > Versioning allows you to monitor the versioning of elements on a specific page: + + +This view shows you the live version (sometimes called "Online") and the draft version (sometimes called "Offline") in a comparison view which helps you to understand what has changed in the draft version. You can also raise the stage of the content for review, you can publish, preview etc. + +Instead of explicitly creating a "Page" type version of the page you can also go ahead and just edit the elements on the page. Transparently an edited element will be versioned and highlighted with green background to reflect the new state. In the page tree a page containing versioned elements will be highlighted with light yellow: + + +In case you also version the page header it will become green in the page tree (here I changed the page title to "Sed non tellus"): + + +Using the Web > Versioning module you will see the workspace content for the page. Obviously the page and one content element is found in draft versions in the workspace: + + +Comparing this view with the previous example where the page was versioned as a "Page" version you will now see that only changed elements appear, not every content element from the page. This type is called "Element" versioning and offers no flexibility in terms of rearranging element but benefits from maintaining all ids and being more straight forward to work with. +If you wish to compare changes in the content between the live and draft version you simply enable "Show difference view" and the display is updated to this: + + +This gives a reviewer a clear idea of the changes that has been performed. The red text is what was removed, the green text is what was added. A click on the button "Send all to Review" will raise the "Editing" stage to "Review" stage. "Publish page" / "Swap page" will perform publishing of all listed elements in the view (unless restrictions apply which is the case if the individual publish/swap buttons for each element is missing). + +Finally, you can also create a "Branch" type version of the page. This will copy not only the page and its content elements but the whole subtree under the page. In order to do so, click the icon of a page, select "Versioning" and in the "Versioning" view you can create a new "Branch" version: + + + +The page tree is now updated to look like this. The darker red page is the root point of the "Branch" version while the lighter red pages is the individual page tree belonging to that version. This type of versioning offers the flexibility to rearrange pages in a branch. + + +The Web > Versioning module displays the "Branch" version like this: + + +When you deal with "Branch" versions you will find a special token, #VEP# in the visual page path in backend modules. This token indicates where the branch point is in the path: + + +The Workspace Manager is available by clicking the workspace-icon next to the workspace selector in the lower right corner of the backend. Or you can access it as the module User > Workspace: + + +The Workspace Manager is the extended version of "Web > Versioning" where you will get an overview of the full workspace content. All versions in the workspace are shown here, can be previewed, managed and published due to your permissions: + + + +Previewing content in the workspace is easy. Generally, you can enable "Frontend Preview" from the checkbox next to the workspace selector in the lower right corner of the backend interface. This will reflect the workspace changes when browsing the frontend website as long as you are logged in as a backend user. + + +Alternatively, you use the Web > View module: + + +Click the page with versioned content in the page tree... + + +... and you will be able to preview the draft content: + + +When you see a preview of a workspace in the frontend you will always be notified by the red box in the bottom of the page: + +You can also click the magnifying-glass found many places in the backend. When you do that in a workspace you will get a special dual-view of the Live and Draft content combined with access to the Web > Versioning module for easy approval or publication: + + + +By default you can use the "Draft workspace" for ad-hoc jobs that doesn?t require strict control over review processes etc. In case you need teams of people with various roles such as author, reviewer and publisher you can create a custom workspace. By doing so you can customize roles, permissions and other features to suit your needs: + + +The custom Workspace is adequately described in the content sensitive help so no more details will be given here. + +The workspace technology offers a simple scheme for staging content through review to publication. In the Workspace Manager or Web > Versioning module you can "raise content " to the next level and attach a comment while doing so: + + + +The stage is raised to "Review" and will be reflected in the interface: + + +Likewise you can take the next step to "Publish" at which point the the workspace owner (of custom workspaces) can uncritically publish assuming the review process has caught any problems - or the workspace owner can act as a final level of review: + + +In case the reviewer or owner finds reasons to reject the content they can do so with an explanation going to the editor: + + +At any time a mouse-over on the Stage control will display the log of events: + + +Notice: The stage feature is only subject to access restrictions inside custom workspaces. In Live and the default Draft workspace the feature is available as a state any user can set and final publishing does not require the "Publish" stage to be reached for any content. + +Publishing content from a workspace can either be done with individual elements, pages including elements or the whole workspace at once. Publishing the full workspace is available from the top of the Workspace Manager: + + +For each element in the list you can access control buttons for publish, swap, release from workspace, edit element, view change history and preview. +Next to the control buttons you see the Lifecycle of content. In the screenshot one of the elements is different from the others: It turns out that this element has actually been published three times. This is possible if the "Swap workspace" buttons are used; They will simply swap the live version with the draft version so that the Live version is taken back into the workspace in exchange. Doing this a few times forth and back will increase the lifecycle counter beyond the otherwise most common state which is "Archive" (published one time). +The other elements shown are all in "Draft" state meaning they have not been published live - yet. + +In the Workspace Manager you can also enable display of sub-elements for "Page" and "Branch" versioning types: + + +This will provide you with a threaded display of the versioned content: + + +Another feature is to enable difference view in the Workspace Manager. By doing so you will see every element compared to its live counterpart (if available) and it will be clear to you what changes has been made: + + + + + +The system log will also reflect operations in the workspace. The "User" column is tagged with the workspace in which the action took place: + + + +Setting up access to workspaces: For the Live and default Draft workspace you will have to configure this in the Backend User and Group records by checkboxes: + + +In the Tools > User Admin module this is also reflected in the comparison view: + + +For custom workspaces users are assigned membership directly in the configuration record of the workspace: + + + +Tip: Although the default settings for upgraded websites will be that all users and groups have access to the Live workspace the intention of the workspace technology is that in most typical cases the average backend user only works in a draft workspace and therefore cannot change live content before a supervisor with access to the Live workspace will enter the backend and publish the workspace content. + +Creating new content: The workspace technology is aimed at being so tough that even a complete website can be built from scratch without changing any live content. Here the Draft Workspace is used to build a complete page structure and dummy content. In the workspace everything looks like if it was live, even when previewed in the frontend with Web > View. + + +Changing to the Live workspace reveals a set of placeholder records. These are necessary to reserve the future position for the new content in the workspace. However, those placeholders are ignored in the live workspace frontend and will therefore not affect any live content. + + + +The Web > List module shows the same reflection. In the screenshot below you can see how pages, content elements, localized versions of content elements, page language overlays and even TypoScript Templates are created as versions in the workspace: + + + +In the Live workspace this is reflected like this by the "invisible" placeholders: + + + +By publication of the workspace these placeholders are substituted with the new versions from the workspace. + +Managing custom workspaces: [This section still misses introduction to the yet missing workspace administration interface in the Workspace Manager.]LocalizationStrategy +Internationalization (i18n) and localization (l10n) issues are handled by the "language" class included by the "template.php" file and instantiated as the global variable $LANG in the backend. +The strategy of localization in TYPO3 is to translate all the parts of the TYPO3 Backend (TBE) interface which are available to everyday users of the CMS such as content editors, contributors, and to a certain extend, administrators. However all developer/admin-parts should remain in English. +The reason for keeping the adminstrator/developer parts in English is that those parts change and expand too quickly. Further it would be a huge task to both implement and translate. And the most important reason is that we want to keep a common vocabulary between developers in the international TYPO3 developer community. So in fact there are strong reasons for not translating the whole system into local languages!Character sets +Currently, local charsets are used by default inside TYPO3. However it is highly recommended to set $TYPO3_CONF_VARS[?BE?][?forceCharset?] = "utf-8" which will force the backend to run in utf-8 regardless of "native" charset. Forcing the charset to "utf-8" also means that all content in the database will be managed in "utf-8" and you might corrupt existing data if you set it after having added content in another charset.How translations are handled by the system +Here is the basic facts about TYPO3s technology to handle localization of the backend interface: +Default language: The default language of TYPO3 is English. (Please respect this in extensions as well!) +Alternative languages: The list of available system languages is defined in the constant TYPO3_languages (hardcoded/defined in config_default.php). This "list" is two-char identification codes representing languages. The code usually reflects a ccTLD related to the language but can be any unique 2-char combination. +Label files: All labels for the backend (and frontend) are stored in locallang-XML (llXML) files located in extensions. They are named according to the scheme locallang*.xml. The default labels must be english! The system extension lang contains labels for the core system. +Notice: "locallang*.php" files is an old alternative still supported but deprecated; They contain the $LOCAL_LANG array in a PHP script which is simply included. Old locallang.php files can be converted to llXML files using the extension extdeveval +Localization methods: The "language" class (from sysext/lang/lang.php) contains methods for requesting labels out of llXML files in the backend (such as getLL() and sL()). The language class also contains an instance of the class "t3lib_cs" where the charsets used for each language are defined. The charset is detected by the "template" class and automatically set for the documents in the backend. +Translation of llXML files: On a local system this is handled by the extension llxmltranslate. Unless the llXML files contains inline translation or a specific reference to an external file, the llxmltranslate tool will write the translation to a corresponding filename in typo3conf/l10n/[language key]/[extension key] (recommended). +Language packs: Due to the large amount of languages for TYPO3 (more than 40) all llXML files in the core and extensions should contain only the default english labels. If no entry is found in the main file for translations, automatically a translation is looked for in typo3conf/l10n/[language key]/[extension key]. The directory typo3conf/l10n/[language key]/ is called the language pack. +For more detailed information about Frontend localization in TYPO3, please refer to the document "Frontend Localization Guide" (doc_l10nguide).Helping translating TYPO3? +Regardless of whether you want to help with an existing language or add a new language you must subscribe to the translator mailing list! That?s rule number 1. Start out by announcing yourself and your intention on that list!Introduce a new language in TYPO3 +If you wish to add a new language to TYPO3, follow these steps: +First, a 2-char unique language key not yet used (Current Language key list: see t3lib/stddb/tbl_be.php:be_users:lang) and charset (utf-8 is default) must be agreed upon. +Contact a core developer and ask him to add the language key to the core. The steps for doing this is defined inside t3lib/config_default.php in a comment just above the definition of the constant TYPO3_languages. +As soon as the language is added to the core you can start translation using the extension llxmltranslate running on the new core. The language pack is automatically created in typo3conf/l10n/[new language key]/Translation teamwork? +Most likely you would like to translate TYPO3 with help from other native speakers from the community. These are the options: +Set up your own translation server: +Install TYPO3 and add those extensions you would like to support in you translation +Install llxmltranslate and use the backend module llXML for translation +Add user accounts for other translators (set their backend language to the language they are supposed to translate) +The result - the language pack in typo3conf/l10n/[language key]/ is ready for distribution. +Pro: You have maximum freedom to keep the translation up-to-date with current core and extensions. You can distrubute the language pack as you like. +Con: You have to intiate the technical set up yourself. +Use official translation server: +Get URL, username and password from translator newsgroup. +If the language is just added you will have to wait until Kasper announces that the translation server is updated with the new core. +Pro: Easy solution, don?t have to install TYPO3 yourself. +Con: You must accept long times between core updates to that server and cannot distrubute your work yourself.Distribution of and contribution to language packs +This is still an open question at this point. The basic technical nature of a language pack is simply that it is a directory in typo3conf/l10n/ inside of which locallang-xml files are found in folders according to the position of their main file. +Scheme: typo3conf/l10n/[lang]/[extkey]/[dir]+[filename] +This leaves various possibilities of distribution and cooperation: +ZIP archives (download)? Language packs can be distributed as a zip file contain translations for any number of extensions. Installation of a language pack is no harder than unzipping a file in the right directory. Groups of extensions (like the core) can come bundled together or extensions can be packed alone. There is currently no public download place for such archives. +EM support? One could imagine that support was built into the Extension Manager: +Download: EM could traverse all installed extensions for locallang*.xml files and send a http-request to some repository for possible translations located there, then writing them into typo3conf/l10n/. EM could even do this transparently based on a configuration of which language packs are wanted for the installation. +Upload: EM could offer to upload local translations of extensions to a localization repository. This could be the solution for distributed translation of un-common extensions since typically one can expect the users of an extension to translate it if not already done - and thus, with a click of a button they might wish to share it. +CVS? Putting the whole language pack into CVS might be an idea for cooperation on a translation. But maybe there will be too many collisions, the language pack in CVS will by time contain translations for too many extensions most people don?t use and it is not likely that all translators have CVS knowledge. +rsync? For both upload and download this could pose a lightweight alternative to CVS - especially for multiple translation servers. But it suffers many of the problems CVS has. + +As a start I would make zip-archives, but my favourite is to integrate support in EM since: +It?s going to be light weight http upload/download +EM knows which extensions are relevant on the system and can install language packs for extensions transparently as a parallel process to installing extensions. +Allows easy sharing of translations made all over the world (thus an answer to the missing online translation tool and translations are made when needed and with understanding of what is translated) +"locallang-XML" (llXML) files +The locallang-XML files contain default labels, possibly inline translations and in addition a lot of meta data used in the translation tool (extension llxmltranslate). +Performance is great with the XML files. This is because the content of the XML file is cached based on the modification time on the xml file. +"locallang-XML" files store the translations of a single language in external files by default. The main reason for using external files for locallang-XML should be distribution considerations: +Typically installations need only English and 1-2 other backend languages, not all 40+! +It allows translators to work on translations independent of extension authors. +Splitting translations means we can better defend storing meta data for translators. + +The format of locallang-XML files can look like this example (shows inline translation of danish): Standard Module labels for Extension Development Evaluator module -EXT:extdeveval/mod1/locallang_mod.xml @@ -1658,7 +1989,31 @@ -You can refer to "TYPO3 Core API" for details about the XML format."language-splitted" syntax +You can refer to "TYPO3 Core API" for details about the XML format.Converting to llXML from locallang.php +If you have locallang.php files in your extensions, please consider to convert them to llXML. This can be done with the extension extdeveval which contains a tool for that. After conversion there is another tool which will separate translations out into the language pack directories. This is of course also highly recommended so the remaining main llXML file contains only default labels!"locallang.php" files (deprecated) + +A "locallang" file looks like this (sysext/lang/locallang_tca.php): + Array (        ?pages? => ?Page?,        ?doktype.I.0? => ?Standard?,        ?doktype.I.1? => ?SysFolder?,        ?doktype.I.2? => ?Recycler?,        ?title? => ?Pagetitle:?,        ?php_tree_stop? => ?Stop page tree:?,        ?is_siteroot? => ?Is root of website:?,        ?storage_pid? => ?General Record Storage page:?,        ?be_users? => ?Backend user?,        ?be_groups? => ?Backend usergroup?,        ?sys_filemounts? => ?Filemount?,    ),    ?dk? => Array (        ?pages? => ?Side?,        ?doktype.I.0? => ?Standard?,        ?doktype.I.1? => ?SysFolder?,        ?doktype.I.2? => ?Papirkurv?,        ?title? => ?Sidetitel:?,        ?php_tree_stop? => ?Stop sidetrę:?,        ?is_siteroot? => ?Siden er websitets rod:?,        ?storage_pid? => ?Generel elementlager-side:?,        ?be_users? => ?Opdaterings bruger?,        ?be_groups? => ?Opdaterings brugergruppe?,        ?sys_filemounts? => ?Filmount?,    ),    ?de? => Array (        ?pages? => ?Seite?,        ?doktype.I.0? => ?Standard?,        ?doktype.I.1? => ?SysOrdner?,        ?doktype.I.2? => ?Papierkorb?,        ?title? => ?Seitentitel:?,        ?php_tree_stop? => ?Seitenbaum stoppen:?,        ?is_siteroot? => ?Ist Anfang der Webseite:?,        ?storage_pid? => ?Allgemeine Datensatzsammlung:?,        ?be_users? => ?Backend Benutzer?,        ?be_groups? => ?Backend Benutzergruppe?,        ?sys_filemounts? => ?Dateifreigaben?,    ), +....[lots of other languages defined]... + +    ?sk? => Array (        ?pages? => ?Strįnka?,        ?doktype.I.0? => ?`tandardnį?,        ?doktype.I.1? => ?Systémovį zlo~ka?,        ?title? => ?Titulka strįnky?,    ),    ?lt? => Array (        ?pages? => ?Puslapis?,        ?doktype.I.0? => ?Standartinis?,        ?doktype.I.1? => ?Sisteminis Aplankas?,        ?doktype.I.2? => ?Šiukšlinė?,        ?title? => ?Puslapio antraštė:?,        ?php_tree_stop? => ?Stapdyti puslapio medį:?,        ?is_siteroot? => ?Ar svetainės šakninis:?,        ?storage_pid? => ?Bendra Puslapio Įrašo saugykla:?,        ?be_users? => ?Administravimo pusės vartotojas?,        ?be_groups? => ?Administravimo pusės vartotojo grupė?,        ?sys_filemounts? => ?Bylų stendas?,    ),);?> + +So the $LOCAL_LANG array has the syntax +$LOCAL_LANG[language_key][label_key] = ?label_value?; +Alternative locallang-syntax for large translation sets +As you can see all available languages are located in the same file! However if a set of labels is very large it is inefficient to load all languages into memory when you need only the default plus the current language to be available (eg. Danish). +Therefore you can split locallang files into a structure with a main file (locallang*.php) and sub-files (locallang*.[langkey].php). An example is sysext/lang/locallang_core.php: + Array (        "labels.openInNewWindow" => "Open in new window",        "labels.goBack" => "Go back",        "labels.makeShortcut" => "Create a shortcut to this page?",        "labels.lockedRecord" => "The user ?%s? began to edit this record %s ago.",        "cm.open" => "Open", +... [lot of more labels here].... +        "cm.save" => "Save",        "cm.unzip" => "Unzip",        "cm.info" => "Info",        "cm.createnew" => "Create new",    ),    ?dk? => "EXT",    ?de? => "EXT",    ?no? => "EXT",    ?it? => "EXT",    ?fr? => "EXT",    ?es? => "EXT",    ?nl? => "EXT",    ?cz? => "EXT",    ?pl? => "EXT",    ?si? => "EXT",    ?fi? => "EXT",    ?tr? => "EXT",    ?se? => "EXT",    ?pt? => "EXT",    ?ru? => "EXT",    ?ro? => "EXT",    ?ch? => "EXT",    ?sk? => "EXT",    ?lt? => "EXT",);?> + +The string token "EXT" set for all the other languages than "default" tells the "language" class that another file contains the language for this language key. For the Danish language this file would be "sysext/lang/locallang_core.dk.php": + "Åben i nyt vindue",            "labels.goBack" => "Gå tilbage",            "labels.makeShortcut" => "Opret genvej til denne side?",            "cm.open" => "Åbn",... [lot of more labels here].... +            "cm.save" => "Gem",            "cm.unzip" => "Unzip",            "cm.info" => "Info",            "cm.createnew" => "Opret ny",);?> + +A requirement is that this "sub-file" sets only it?s own language key (here "dk") in the $LOCAL_LANG array. Thus simply including this file after the main file will add the whole "dk" key to the existing $LOCAL_LANG array with no need for array merging! +Notice another detail which is a general feature of $LOCAL_LANG arrays: The label key ?labels.lockedRecord? is not specified for the Danish translation. That simply means that the value of the "default" key (English) will be shown until that value will be added by the Danish translator! +Notice: locallang.php files are deprecated! Use locallang-XML files instead!"language-splitted" syntax (deprecated) An old concept called language-split has been around for use with typically table-names, field names etc. in $TCA. This concept is based on a single string with labels separated by | according to the number of system languages defined in the TYPO3_languages constant. But this approach is now depricated for the future because it is not very scalable and it?s VERY hard to maintain properly. Therefore the locallang concept is required for use anywhere a value is defined to be language-splitted (LS). Instead of specifying a number of labels separated with | you simply write a code, which refers to a locallang-file/label inside of that. Syntax is LLL:[file-reference of locallang file relative to PATH_site]:[key-name]:[extra settings]. File-reference should be a filename relative to PATH_site. You can prepend the reference with EXT:[extkey]/ in order to refer to locallang-files from extensions.Example: @@ -1749,16 +2104,7 @@ The filepath of "typo3conf/llor_test.php" is relative to the PATH_site constant. You could also keep the file in an extension in which case you would have to enter the file reference like ?EXT:myext/llor_test.php? - and the file will automatically be located wherever you extension is installed. -This example includes a function call to $LANG->sL(). If the labels are fetched by $LANG->getLL() as they are in most modules you will have to make sure that the locallang file you need to override was included by the function $LANG->includeLLFile() since that will detect any "XLLfile" you might have configured - otherwise the API will not work of course.Update current languages -This is done on typo3.org directly as all language translations are handled through extensions. You can help out, for example as an assisting translator. -Technical notice: label keys prefixed with "_" (fx. ?_mylabel? => ...) will be ignored by the translation tool on typo3.org.Introduce a new language in TYPO3 -Adding a new language to TYPO3 requires two steps: -Ask Kasper to have the language added. If he approves it, you must give him a) your typo3.org username (you will be the chief translator) and b) tell him which charset you want to use, c) which "language key" will be appropriate to use (eg. "dk" for Danish (ccTLD) or "mr" for "Marsian" (any ccTLD? Anyways, they haven?t found life yet...)). Then he will create the language on typo3.org and you can begin with the translation process right away.Criteria for creating a new language mainly is that you have thought twice whether you want to undertake the work! It?s a lot of labels to translate and we want to see commitment to carry it through, at least for the most important system parts! Please read this document also to see how it works. And finally you might want to consider recruiting assisting translators who can help you! -Secondly the TYPO3 source code will have to be updated on at least one point: -To add "marsian" language key "mr", modify t3lib/config_default.php: -define(?TYPO3_languages?, ?default|dk|de|no|it|fr|es|nl|cz|pl|si|fi|tr|se|pt|ru|ro|ch|sk|lt|mr?); - -This line will also tell you about other places to add the new language. However this source code modification will also be done by Kasper of course, but this is for your information so you can temporarily fix your local source to fit the new language.Context Sensitive Help (CSH) +This example includes a function call to $LANG->sL(). If the labels are fetched by $LANG->getLL() as they are in most modules you will have to make sure that the locallang file you need to override was included by the function $LANG->includeLLFile() since that will detect any "XLLfile" you might have configured - otherwise the API will not work of course.Context Sensitive Help (CSH) TYPO3 offers a full API for adding Context Sensitive Help to especially all database tables and fields. This is normally expressed by small comments and an icon linking to a window with a full explanation of a field - or a feature in a module if you choose to use it in that way. @@ -1844,8 +2190,7 @@ Observe the label-key naming by the syntax [fieldname].[type-key].[special option] (see previous section) Label-key names that are prefixed "_" can safely be used - the prefix is simply removed! This is encouraged for the "seeAlso" and "image" field names since those are in common for all languages and therefore doesn?t need translation (the typo3.org translation tool ignores label-keys which are prefixed "_"). When used with database tables: Blank fieldnames are used for information about the database table itself - non-blank fieldnames are expected to point to the actual fieldnames. -For the locallang-XML files which are translated by a backend module you can place images in a subfolder, "cshimages/", to where the locallang-file is located and they will be shown in a selector box inside the translation tool. -There is a reserved extension key prefix, "csh_" which is reserved for language specific collections of "Context Sensitive Help". This can be used from "locallang-XML" files quite easily so the big load of CSH content for each language is located in isolated extensions. The feature is called "external include files" and enables the main locallang-XML file to specify an "external" file in an extension which carries translations for a single language.Syntax for the type-keys content +For the locallang-XML files which are translated by a backend module you can place images in a subfolder, "cshimages/", to where the locallang-file is located and they will be shown in a selector box inside the translation tool.Syntax for the type-keys content type-key Syntax description @@ -2324,7 +2669,7 @@ Set "775" permissions on files and folders that should be writeable by both Set "[user1].[user2]" owner/group on files and foldersWrite protection of source code The source code needs to be writeable at certain points. Lets define some rules:Backend / Source code: -Generally you can write protect the whole TYPO3 source code (that is the typo3_src/* (more specifically typo3/, tslib/, t3lib/) directories and their contents) +Generally you can write protect the whole TYPO3 source code (that is the typo3_src/* (more specifically typo3/ and t3lib/) directories and their contents) ... except: "typo3/ext/" if you wish TYPO3 to install global extensions for you.Frontend (local website): typo3temp/, uploads/ (+ subdirs) and typo3conf/ (+ subdirs) must be writeable. The ownership of the files should be the webserver user executing the scripts. @@ -2334,7 +2679,7 @@ Notice: A typical mistake on UNIX systems regarding the write permissions is if you look at the write permission for eg. typo3conf/localconf.php and see that this file should be writeable. If TYPO3 tells you that it is not writeable it?s most likely because you didn?t allow PHP to write to the typo3conf/ directory as well!Changing the default typo3/ directory By default TYPO3 is administrated from the directory typo3/. You can change (rename) that so the backend is available from another directory, eg. my_typo3_admin_dir/. But the frontend and backend is tied together in some ways that mean you?ll have to change parts of the source code. That is relatively easy if you follow these guidelines: Rename the typo3/ dir/softlink to my_typo3_admin_dir/. Notice that the backend directory must always be a sub directory to the website (extensions inside + frontend edit relies on the backend to be there). Further it cannot be a sub-sub-directory either! (This will work only partially and is currently not intended to be fixed). -Search for the string ?define("TYPO3_mainDir"?. At least four scripts will be found: tslib/index_ts.php (the index.php file), tslib/showpic.php, t3lib/thumbs.php and typo3/init.php. With each instance change the constant definition from typo3/ to my_typo3_admin_dir/. +Search for the string ?define("TYPO3_mainDir"?. At least four scripts will be found: typo3/sysext/cms/tslib/index_ts.php (the index.php file), typo3/sysext/cms/tslib/showpic.php, t3lib/thumbs.php and typo3/init.php. With each instance change the constant definition from typo3/ to my_typo3_admin_dir/. Any local extensions (those installed in typo3conf/ext/) that has backend modules in them (those with conf.php files) MUST have their $BACK_PATH definition in the conf.php file changed! If they are installed by the extension manager everything should be fine, but if not, you must change manually. You will receive an error something like this:Warning: Failed opening ?../../../../typo3/init.php? for inclusion... Rarely: The extension direct_mail has two cron-scripts, dmailerd.phpcron and returnmail.phpsh. They have typo3/ hardcoded as admin directory as well. If you use these scripts, you will have to change that too. @@ -2455,7 +2800,8 @@ (The GPL license can be found in the file GPL.txt inside the TYPO3 source code)AppendixImageMagickIntroduction ImageMagick has been used since the dawn of times by TYPO3. What we didn?t know back then is that ImageMagick would have a record of changing APIs all the time which has been a real pain in the behind for us during the years. Also certain features has been changed, some has been made significantly slower, some removed totally and some got a poorer quality in our opinion. All this has lead to the recommendation of using ImageMagick 4.2.9 - a 6 years old version. -Today, I?m personally using the latest 5.x version since faster computers has now compensated for the slowness of the features that made version 5 unacceptable at first. So TYPO3 does work and works well with 5+ versions of ImageMagick. I?m not sure version 6 is supported yet - some reports claims it has changed again... +Starting with TYPO3 3.8.0, support for GraphicsMagick has been introduced. GraphicsMagick is a fork of ImageMagick whose mission is to build a more stable version of ImageMagick which is really the case. +Refer to the Install Tool for more information about using GraphicsMagick. Usually it should be detected automatically and be preferred over ImageMagick if both are found. We recommend to use it and forget about all those ImageMagick troubles... The following pages contain old notes about the ImageMagick problems. They are preserved for historical reasons mostly.Filesystem Locations (rpms): NO LZW: 4.2.9: /usr/X11R6/bin/