.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ================================== Browser Tutorial Localization (en) ================================== :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed: 2009-09-25T11:42:13 :Classification: browser_tut_localization_en :Description: Tutorial Localization for the Browser :Keywords: browser, tutorial, localization, language, language overlay, lang_ol, translation, forDevelopers :Author: Dirk Wildt, Die Netzmacher :Email: wildt.at.die-netzmacher.de :Website: http://die-netzmacher.de :Language: en |img-1| |img-2| extKey: browser\_tut\_localization\_en |img-3| .. _Browser-Tutorial-Localization-en: Browser Tutorial Localization (en) ================================== |img-4| Version: 3.0.1, 2009-09-25 - Version is corresponding with the version of the Browser. Extension Key: browser\_tut\_localization\_en - Tutorial for the extension Browser (extkey: browser) Language: en Keywords: browser, tutorial, localization, language, language overlay, lang\_ol, translation, forDevelopers Copyright 2009, Dirk Wildt, Die Netzmacher, This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.typo3.org .. _Table-of-Contents: Table of Contents ----------------- `Browser Tutorial Localization (en) 1 <#1.Browser%20Tutorial%20Localization%20(en)|outline>`_ `Introduction 3 <#1.1.Introduction|outline>`_ `What does it do? 3 <#1.1.1.What%20does%20it%20do_|outline>`_ `Version 3 <#1.1.2.Version|outline>`_ `Further Information 3 <#1.1.3.Further%20Information|outline>`_ `This tutorial in PDF format 3 <#1.1.3.1.This%20tutorial%20in%20PDF%20format|outline>`_ `Browser Manual and Browser Tutorial Library 3 <#1.1.3.2.Browser%20Man ual%20and%20Browser%20Tutorial%20Library|outline>`_ `TYPO3 Localization Guide 3 <#1.1.3.3.TYPO3%20Localization%20Guide|outline>`_ `TYPO3 Core API 3 <#1.1.3.4.TYPO3%20Core%20API|outline>`_ `Localization 4 <#1.2.Localization|outline>`_ `The Difference between Translation and Localization 4 <#1.2.1.The%20D ifference%20between%20Translation%20and%20Localization|outline>`_ `Translation 4 <#1.2.1.1.Translation|outline>`_ `Localization 4 <#1.2.1.2.Localization|outline>`_ `The Difference between Local Tables and Foreign Tables 4 <#1.2.2.The% 20Difference%20between%20Local%20Tables%20and%20Foreign%20Tables|outli ne>`_ `Example tt\_news 4 <#1.2.2.1.Example%20tt_news|outline>`_ `Tutorial 5 <#1.3.Tutorial|outline>`_ `Requirements 5 <#1.3.1.Requirements|outline>`_ `Tables 5 <#1.3.1.1.Tables|outline>`_ `TYPO3 Languages 5 <#1.3.1.1.TYPO3%20Languages|outline>`_ `Translated Page with the Browser plugin 6 <#1.3.1.2.Translated%20Page%20with%20the%20Browser%20plugin|outline>`_ `Translated Sysfolder 6 <#1.3.1.3.Translated%20Sysfolder|outline>`_ `Localized Local Table 7 <#1.3.1.4.Localized%20Local%20Table|outline>`_ `Foreign Table with Language Overlay 7 <#1.3.1.4.Foreign%20Table%20with%20Language%20Overlay|outline>`_ `TypoScript 8 <#1.3.2.TypoScript|outline>`_ `Copy the Code 8 <#1.3.2.1.Copy%20the%20Code|outline>`_ `What do you need 8 <#1.3.2.2.What%20do%20you%20need|outline>`_ `Language configuration 8 <#1.3.2.3.Language%20configuration|outline>`_ `Language Menu 8 <#1.3.2.4.Language%20Menu|outline>`_ `Browser 9 <#1.3.2.5.Browser|outline>`_ `Backend Illustration 10 <#1.3.2.6.Backend%20Illustration|outline>`_ `Frontend Illustration 11 <#1.3.2.7.Frontend%20Illustration|outline>`_ `Reference 12 <#1.4.Reference|outline>`_ `FAQ 13 <#1.5.FAQ|outline>`_ `How do I localize tables in my own extension? 13 <#1.5.1.How%20do%20I %20localize%20tables%20in%20my%20own%20extension_|outline>`_ `Local Table - Localization 13 <#1.5.1.1.Local%20Table%20-%20Localization|outline>`_ `Foreign Tables - Language Overlay 13 <#1.5.1.2.Foreign%20Tables%20-%20Language%20Overlay|outline>`_ `What's the definition off? 14 <#1.5.2.What's%20the%20definition%20off_|outline>`_ `sys\_language\_uid 14 <#1.5.2.1.sys_language_uid|outline>`_ `sys\_language\_mode 14 <#1.5.2.2.sys_language_mode|outline>`_ `sys\_language\_overlay 14 <#1.5.2.3.sys_language_overlay|outline>`_ `Helpful suggestions 15 <#1.6.Helpful%20suggestions|outline>`_ `Change Log 16 <#1.7.Change%20Log|outline>`_ `Illustration Index 17 <#1.8.Illustration%20Index|outline>`_ .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ This is a tutorial for the extension Browser (extkey: browser). It is a step-by-step introduction for Localization only. .. _Version: Version ^^^^^^^ The version of Browser Tutorial Localization (en) is corresponding with the version of the extension Browser. The Browser supports localization from version 3.0.0. .. _Further-Information: Further Information ^^^^^^^^^^^^^^^^^^^ |img-5| Illustration 1: Tutorial in PDF format This tutorial in PDF format You find this tutorial as a PDF file at - doc/manual.pdf - `http://typo3.org/extensions/repository/view/browser\_tut\_en\_2/curre nt/info/?tx\_terfe\_pi1%5BdownloadFile%5D=doc%252Fmanual.pdf `_ .. _Browser-Manual-and-Browser-Tutorial-Library: Browser Manual and Browser Tutorial Library """"""""""""""""""""""""""""""""""""""""""" Manual: The Browser has it's own manual (with the reference of course). - HTML `http://typo3.org/documentation/document-library/extension- manuals/browser/current/ `_ - PDF: `http://typo3.org/extensions/repository/view/browser/current/info /?tx\_terfe\_pi1%5BdownloadFile%5D=doc%252Fmanual.pdf `_ Tutorial Library: Tutorial Library for the Browser with a lot of step- by-step introductions. - HTML: `http://typo3.org/documentation/document-library/extension- manuals/browser\_tut\_basics\_en/current/ `_ - PDF: `http://typo3.org/extensions/repository/view/browser\_tut\_basics \_en/current/info/?tx\_terfe\_pi1%5BdownloadFile%5D=doc%252Fmanual.pdf `_ .. _TYPO3-Localization-Guide: TYPO3 Localization Guide """""""""""""""""""""""" If you want to know more about TYPO3 localization, please read the official TYPO3 "Frontend Localization Guide": `http://typo3.org/documentation/document-library/core- documentation/doc\_l10nguide/current/ `_ .. _TYPO3-Core-API: TYPO3 Core API """""""""""""" The TYPO3 Core API has a lot of information in context with the localization and the TCA. `http://typo3.org/documentation/document-library/core- documentation/doc\_core\_api/current/ `_ .. _Localization: Localization ------------ .. _The-Difference-between-Translation-and-Localization: The Difference between Translation and Localization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Localization is easier to understand, if you know the explanation out of the TYPO3 "Frontend Localization Guide": .. _Translation: Translation """"""""""" Translation means that a specific composition of words are translated to another language. In other words: If there is a header and an image in the default language, so there will be in the translation. No more, no less. .. _Localization: Localization """""""""""" Localization means more broadly that a page is represented in another language. This of course means information in that language ("translation") but could also include alternative templates, additional composition of content directed to another audience etc. In other words: There might be another number of headers and images than in the default language. .. _The-Difference-between-Local-Tables-and-Foreign-Tables: The Difference between Local Tables and Foreign Tables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. _Example-tt-news: Example tt\_news """""""""""""""" I.e. we are using the three languages - English (default language), - German and - French in our TYPO3 installation. We have a news with this fields and values in the default language (English): - title: New President - image: barack\_obama.jpg - category: lead story If we translate the news to German (adding a second record tt\_news with the language id of the German language) the TCA will display: - title: [Translate to German] New President - category: Categories from the translation original of this record: lead story [12] The image field won't be displayed - it isn't editable. The category field will be displayed although like the example above, but it isn't editable neither. **Why are the field image and the field category not editable?** Image isn't editable, because we need the Barack Obama photo once only: The president looks alike in English, German or French language. We don't like to upload the same photo for every language. And we can't upload it, because the image field has the property l10n\_mode = exclude in the TCA array. It won't be displayed, if the backend editor has choosen another language than the default language. We have a similar case with the field category: We don't need another category for the news, we need only a translated phrase like "Aufmacher" or "accroche". The table tt\_news\_cat has the field title\_lang\_ol (lang\_ol means: language overlay) to enable translation. Example of tt\_news\_cat: - title: lead story - title\_lang\_ol: de:Aufmacher\|fr:accroche `:sup:`0` <#sdfootnote1sym>`_ .. _Tutorial: Tutorial -------- .. _Requirements: Requirements ^^^^^^^^^^^^ .. _Tables: Tables """""" We need tables with localization and language overlay. The extension tt\_news is a good example: tt\_news is a localized table with the fields: |img-6| - - sys\_language\_uid - l18n\_parent - l18n\_diffsource - tt\_news\_cat is a table with a language overlay field: |img-6| title\_lang\_ol .. _TYPO3-Languages: TYPO3 Languages """"""""""""""" Extend your TYPO3 installation with languages. |img-6| In our example above we have - a default language (there is no record in the table "Website Language"). The default is German and has the uid 0. - Englisch (uid 1) and - Französisch (uid 2) .. _Translated-Page-with-the-Browser-plugin: Translated Page with the Browser plugin """"""""""""""""""""""""""""""""""""""" Create a page and add the plugin Browser. Translate the page to English and French. You need a translated page, if you want to display Browser results in a non default language. You need a translated plugin Browser only, if you like to use a different header in a non default language. |img-6| The starting point of the plugin Browser is the folder with your news. .. _Translated-Sysfolder: Translated Sysfolder """""""""""""""""""" The sysfolder with your records (in this case: news) has to be translated too. Otherwise you can't store a record in another language than the default language. |img-6| .. _Localized-Local-Table: Localized Local Table """"""""""""""""""""" The illustration below displays a localized local table: tt\_news has translated records. |img-6| The content of your sysfolder should be look like the illustration above. The alternative page language records. The first news is translated into English but not into French. You can translate (localize) the news into French by clicking the French icon. The second news isn't translated in any language. .. _Foreign-Table-with-Language-Overlay: Foreign Table with Language Overlay """"""""""""""""""""""""""""""""""" The illustration below displays the foreign table with a language overload field: tt\_news\_cat has translated categories. |img-6| **Please note:** The Browser enables language overlay phrases with a language prefix like en:Lead Story\|fr:Accroche This is an enhancement of the common language overlay phrases without an language prefix. If you like to use the common way without language prefixes please configure: plugin.tx\_browser\_pi1.advanced.localization.TCA.value.langPrefix = 0 .. _TypoScript: TypoScript ^^^^^^^^^^ .. _Copy-the-Code: Copy the Code """"""""""""" You find the whole TypoScript code in res/setup.txt You can copy it into your page template. .. _What-do-you-need: What do you need """""""""""""""" - The page with the browser plugin needs an TypoScript template. - Include the include static template from the browser. - Configure in the field [setup] the: language configuration a language menu the Browser configuration .. _Language-configuration: Language configuration """""""""""""""""""""" If your are uisng more than the default language, you have to configure the behavior of each language. config { linkVars = L metaCharset = UTF-8 sys\_language\_uid = 0 sys\_language\_mode = strict sys\_language\_overlay = 0 language = de locale\_all = de\_DE htmlTag\_langKey = de } [globalVar = GP:L = 1] config { sys\_language\_uid = 1 sys\_language\_mode = content\_fallback sys\_language\_overlay = 1 language = en locale\_all = en\_GB htmlTag\_langKey = en } [global] [globalVar = GP:L = 2] config { sys\_language\_uid = 2 sys\_language\_mode = strict sys\_language\_overlay = hideNonTranslated language = fr locale\_all = fr\_FR htmlTag\_langKey = fr } [global] .. _Language-Menu: Language Menu """"""""""""" The code // If we have single view, the menu should have the record uid temp.addParams = COA temp.addParams { 10 = TEXT 10 { tx\_browser\_pi1[showUid] dataWrap = &tx\_browser\_pi1[showUid]={GPvar:tx\_browser\_pi1\|showUid} if.isTrue.data = GPvar:tx\_browser\_pi1\|showUid } } // The language menu temp.nav\_language = HMENU temp.nav\_language { special = language special.value = 0,1,2 special.normalWhenNoLanguage = 1 1 = TMENU 1{ NO { linkWrap = \| \|\| \| linkWrap =
  • \|
    • \|\|
  • \|
    • \|\|
  • \|
    • stdWrap.override = Deutsch \|\| English \|\| Französisch additionalParams { cObject < temp.addParams } } ACT = 1 ACT { doNotLinkIt = 1 linkWrap = \| \|\| \| linkWrap =
  • \|
    • \|\|
  • \|
    • \|\|
  • \|
    • stdWrap.override = Deutsch \|\| English \|\| Französisch } wrap =
      \|
    } } // Add the language menu to your page object // Adapt this to your page object page.10.subparts.navi { 10 < temp.nav\_language 22 > } // Adapt this to your page object .. _Browser: Browser """"""" // Two list views and two single views plugin.tx\_browser\_pi1. views { list.1.select = tt\_news.title, tt\_news\_cat.title list.1.select = tt\_news.title, tt\_news.image single.1.select = tt\_news.title, tt\_news.author, tt\_news\_cat.title, tt\_news.short, \tt\_news.datetime single.1.select = tt\_news.title, tt\_news.bodytext, tt\_news.image, tt\_news.imagecaption, \tt\_news.imagealttext, tt\_news.imagetitletext, tt\_news\_cat.title marker.my\_title { value = My News List lang.de = Meine Nachrichten Liste lang.fr = Nouvelles Tableau wrap =

    \|

    } } .. _Backend-Illustration: Backend Illustration """""""""""""""""""" |img-6| **Page** The page "Nachrichten" with - three Browser plugins, - two alternative page language records and - the template. We call the template in the syntax: - type\_page-name\_template-uid - example: +page\_nachrichten\_382 **Template with Setup** |img-6| |img-6| .. _Frontend-Illustration: Frontend Illustration """"""""""""""""""""" We have different results in the frontend - depending on the language configuration. .. ### BEGIN~OF~TABLE ### .. _img-6: |img-6| ~~~~~~~ .. container:: table-row a |img-6| b |img-6| c |img-6| .. _German-default-language: **German (default language)** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. container:: table-row a **German (default language)** All records are in German. b **English** Records are displayed, which are translated into English. If they aren't translated, they are displayed in the default language German. c **French** Records are displayed only, if they are translated into French. .. _TypoScript: **TypoScript** ~~~~~~~~~~~~~~ .. container:: table-row a **TypoScript** config { sys\_language\_uid = 0 sys\_language\_mode = strict sys\_language\_overlay = 0 language = de locale\_all = de\_DE htmlTag\_langKey = de } b **TypoScript** config { sys\_language\_uid = 1 sys\_language\_mode = \content\_fallback sys\_language\_overlay = 1 language = en locale\_all = en\_GB htmlTag\_langKey = en } c **TypoScript** config { sys\_language\_uid = 2 sys\_language\_mode = strict sys\_language\_overlay = \hideNonTranslated language = fr locale\_all = fr\_FR htmlTag\_langKey = fr } .. ###### END~OF~TABLE ###### If you want to know more about - sys\_language\_uid - sys\_language\_mode - sys\_language\_overlay please read the section "What's the definition off?" in the FAQ below. .. _Reference: Reference --------- See the section Reference / Localization in the Browsers manual in - HTML `http://typo3.org/documentation/document-library/extension- manuals/browser/current/ `_ - PDF: `http://typo3.org/extensions/repository/view/browser/current/info /?tx\_terfe\_pi1%5BdownloadFile%5D=doc%252Fmanual.pdf `_ .. _FAQ: FAQ --- .. _How-do-I-localize-tables-in-my-own-extension: How do I localize tables in my own extension? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The principle is: - Localize your local table. - Don't localize foreign tables, but extend it with fields to enable to overlay the language. .. _Local-Table-Localization: Local Table - Localization """""""""""""""""""""""""" Localize your local table means: Extend your table with the TYPO3 localization fields. This fields are: - sys\_language\_uid - l18n\_parent - l18n\_diffsource If your are developing with the assistance of the kickstarter you have to activate the option "Enable localization features" only (like in the screen shot below) - that's all. |img-6| .. _Foreign-Tables-Language-Overlay: Foreign Tables - Language Overlay """"""""""""""""""""""""""""""""" The business of foreign tables is the same like the business of the tt\_news\_cat (categories) usually. In this case don't localize the table. Extend your foreign table for each field which need a translation with its name and the appendix "\_lang\_ol" like this example: - title: The title in the default language - title\_lang\_ol: A list of translated phrases for overlaying the default language phrase. Example with values: - title: lead story - title\_lang\_ol: de:Aufmacher\|fr:accroche If you need the foreign table for more jobs than categorizing it should be a good idea to localize the foreign table in the same way like the local table. .. _What-s-the-definition-off: What's the definition off? ^^^^^^^^^^^^^^^^^^^^^^^^^^ The next section is from the TYPO3 TypoScript Reference. .. _sys-language-uid: sys\_language\_uid """""""""""""""""" Integer: This value points to the uid of a record from the "sys\_language" table and if set, this means that various parts of the frontend display code will select records which are assigned to this language. See ->SELECT Internally, the value is depending on whether a Alternative Page Language record can be found with that language. If not, the value will default to zero (default language) except if "sys\_language\_mode" is set to a value like "content\_fallback". .. _sys-language-mode: sys\_language\_mode """"""""""""""""""" String: Setting various modes of handling localization. The syntax is "[keyword] ; [value]". Possible keywords are: - [default] - The system will look for a translation of the page (from "Alternative Page Language" table) and if it is not found it will fall back to the default language and display that. - content\_fallback - [ Recommended ] The system will always operate with the selected language even if the page is not translated with a page overlay record. This will keep menus etc. translated. However, the content on the page can still fall back to another language, defined by the value of this keyword, eg. "content\_fallback ; 1,0" to fall back to the content of sys\_language\_uid 1 and if that is not present either, to default (0). - strict - The system will report an error if the requested translation does not exist. Basically this means that all pages with gray background in the Web>Info / Localization overview module will fail (they would otherwise fall back to default language in one or another way). - ignore - The system will stay with the selected language even if the page is not translated and there's no content available in this language, so you can handle that situation on your own then. .. _sys-language-overlay: sys\_language\_overlay """""""""""""""""""""" Boolean / Keyword: If set, records from certain tables selected by the CONTENT cObject using the "languageField" setting will select the default language (0) instead of any language set by sys\_language\_uid / sys\_language\_mode. In addition the system will look for a translation of the selected record and overlay configured fields. The requirements for this is that the table is configured with "languageField" and "transOrigPointerField" in the [ctrl] section of $TCA. Also, exclusion of certain fields can be done with the "l10n\_mode" directive in the field-configuration of $TCA. For backend administration this requires that you configure the "Web>Page" module to display content elements accordingly; That each default element is shown and next to it any translation found. This configuration can be done with Page TSconfig for a section of the website using the object path "mod.web\_layout.defLangBinding = 1". Keyword: hideNonTranslated: If this keyword is used a record that has no translation will not be shown. The default is that records with no translation will show up in the default language. .. _Helpful-suggestions: Helpful suggestions ------------------- If you have helpful suggestions, feel free to contact me: wildt.at .die-netzmacher.de. .. _Change-Log: Change Log ---------- 3.0.1 Publishing 2.6.1 Initial release .. _Illustration-Index: Illustration Index ------------------ Illustration 1: Tutorial in PDF format 3 Illustration 2: The table tt\_news in phpMyAdmin with localization fields. 5 Illustration 3: Table tt\_news\_cat in phpMyAdmin with the language overlay field. 5 Illustration 4: TYPO3 installation with two language records. 5 Illustration 5: The page "Nachrichten" is translated into English and French. Every translated page contains the Browser plugin. 6 Illustration 6: The sysfolder "Nachrichten" is translated into English and French. 6 Illustration 7: Sysfolder with the records in the list view. 7 Illustration 8: Sysfolder with the categories in the list view. 7 Illustration 9: Page "Nachrichten" in the Backend. 10 Illustration 10: Template with the code in the setup field. 10 Illustration 11: Include static template from the Browser. 10 Illustration 12: List View in German 11 Illustration 13: List View in Englisch 11 Illustration 14: List View in French 11 Illustration 15: Localization with the kickstarter. 13 `0 <#sdfootnote1anc>`_ If you like to use phrases without a language prefix, please deactivate plugin.tx\_browser\_pi1.advanced.localization.TCA.value.langPrefix. 17 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. |img-2| image:: img-2.png .. :border: 0 .. :height: 27 .. :hspace: 4 .. :id: Grafik2 .. :name: Grafik2 .. :width: 98 .. |img-3| image:: img-3.png .. :align: bottom .. :border: 0 .. :height: 27 .. :id: graphics25 .. :name: graphics25 .. :width: 30 .. |img-4| image:: img-4.png .. :align: bottom .. :border: 0 .. :height: 268 .. :id: graphics5 .. :name: graphics5 .. :width: 302 .. |img-5| image:: img-5.jpeg .. :align: left .. :border: 0 .. :height: 205 .. :id: graphics2 .. :name: graphics2 .. :width: 227 .. |img-6| image:: data: :alt: Frame3 .. :align: bottom .. :id: Frame3 .. :name: Frame3