Skip to content
This repository
Browse code

Caveats section for README

  • Loading branch information...
commit 1d7a84b6379b9e684731fbf7b2f133ae9bb7706d 1 parent 745b2bc
Ingo Schommer authored

Showing 1 changed file with 38 additions and 34 deletions. Show diff stats Hide diff stats

  1. 72  docs/en/index.md
72  docs/en/index.md
Source Rendered
@@ -4,13 +4,12 @@
4 4
 
5 5
 This page introduces developers to using the CMS for creating content in multiple languages.
6 6
 
7  
-Please refer to the `i18n` class in `sapphire` for a internationalization, globalization and localization support of built-in datatypes as well as translating templates and PHP code.
  7
+Please refer to the [`i18n` class](http://doc.silverstripe.org/framework/en/topics/i18n) 
  8
+in SilverStripe framework for a internationalization, globalization and 
  9
+localization support of built-in datatypes as well as translating templates and PHP code.
8 10
 
9  
-Translations can be enabled for all subclasses of `[api:DataObject]`, so it can easily be implemented into existing code
10  
-with minimal interference.
11  
-
12  
-Warning: If you're upgrading from a SilverStripe version prior to 2.3.2, please migrate your datamodel before using the
13  
-extension (see below).
  11
+Translations can be enabled for all subclasses of [`DataObject`](http://doc.silverstripe.org/framework/en/topics/datamodel), 
  12
+so it can easily be implemented into existing code with minimal interference.
14 13
 
15 14
 ## Screenshots
16 15
 
@@ -32,6 +31,35 @@ extension (see below).
32 31
 *CMS: Create a new translation*
33 32
 
34 33
 
  34
+## Caveats
  35
+
  36
+There are several ways to model multilingual content in a relational database.
  37
+It is important to understand these differences in order to make an informed
  38
+decision about which one fits your content model best. 
  39
+
  40
+ * **Storage in language columns**: Each translated value is stored in a new database column
  41
+ alongside its original record, e.g. a `Content` column gets extended to `Content_de` and `Content_fr`.
  42
+   
  43
+    * Advantages: Translation can be limited to certain columns.
  44
+    * Disadvantages: If applied to complex data like hierarchical pages, it only works if the content structure
  45
+ is very similar between languages. It would be difficult to e.g. have a new page section just in one language,
  46
+ and still retain all the framework's features (e.g. permission checks).
  47
+ * **Storage in language rows**: Each translated record gets copied to a new row in the same table,
  48
+ retaining the original database column layout.
  49
+   
  50
+    * Advantages: Allows for flexible structures like page trees per language,
  51
+ and permission checks per language. Works transparently with most other modules which modify queries
  52
+ (e.g. the "subsites" module). 
  53
+    * Disadvantages: All-or-nothing approach to column translation (including columns where translation
  54
+  doesn't make much sense, like numeric values). More complex data model with relational tables.
  55
+
  56
+The Translatable module uses the "Storage in language rows" approach.
  57
+
  58
+Alternatives:
  59
+
  60
+ * UncleCheese's [TranslatableDataObject](http://www.leftandmain.com/silverstripe-tips/2012/04/03/translatabledataobject-insanely-simple-translation/) (open source)
  61
+ * Kreationsbyran's [Multilingual Module 2.0](http://www.kreationsbyran.se/blogg/multilingual-module-2-0-for-silverstripe-cms-3-0/) (commercial)
  62
+
35 63
 ## Usage
36 64
 
37 65
 ### Configuration
@@ -187,7 +215,7 @@ attach this behaviour to custom fields by using Translatable_Transformation as s
187 215
 
188 216
 
189 217
 
190  
-### Translating theHomepage
  218
+### Translating the Homepage
191 219
 
192 220
 Every homepage has a distinct URL, the default language is /home, a German translation by default would be /home-de_DE.
193 221
 They can be accessed like any other translated page. If you want to access different homepages from the "root" without a
@@ -362,12 +390,6 @@ Example:
362 390
 	<% end_control %>
363 391
 
364 392
 
365  
-### Language Chooser Widget
366  
-
367  
-You can use a widget on your website to provide a list of links for switching languages:
368  
-[download](http://silverstripe.org/Language-Chooser-Widget-2/)
369  
-
370  
-
371 393
 ### Enabling the _t() function in templates 
372 394
 
373 395
 If you're looking to use [the _t() function](http://doc.silverstripe.com/doku.php?id=i18n#the_t_function) in template
@@ -375,29 +397,11 @@ files, you'll need to [set the i18n locale](/topics/translation#setting_the_i18n
375 397
 
376 398
 (The reasoning is as follows: Translatable doesn't set the i18n locale. Historically these were two separate systems,
377 399
 but they're reasonably interchangeable for a front-end website. The distinction is mainly valid for the CMS, because you
378  
-want the CMS to be in English (`[api:i18n]`), but edit pages in different languages (`[api:Translatable]`).)
379  
-
380  
-### Migrating from 2.1 datamodel
381  
-
382  
-The datamodel of `[api:Translatable]` changed significantly between its original release in SilverStripe 2.1 and SilverStripe
383  
-2.3.2. See our [discussion on the
384  
-mailinglist](http://groups.google.com/group/silverstripe-dev/browse_thread/thread/91e26e1f78d3c1b4/bd276dd5bbc56283?lnk=gst&q=translatable#bd276dd5bbc56283).
385  
-
386  
-To migrate a database that was built with SilverStripe 2.1.x or 2.2.x, follow these steps:
387  
-
388  
-*  Upgrade your SilverStripe installation to at least 2.3.2 (see [upgrading](/installation/upgrading))
389  
-*  Backup your database content
390  
-*  Login as an administrator
391  
-*  Run `http://mysite.com/dev/build`
392  
-*  Run `http://mysite.com/dev/tasks/MigrateTranslatableTask`
393  
-
394  
-Please see the `[api:MigrateTranslatableTask]` for
395  
-limitations of this migration task - not all your data will be preserved.
396  
-
  400
+want the CMS to be in English (`i18n`), but edit pages in different languages (`Translatable`).)
397 401
 
398 402
 ### Setting the i18n locale
399 403
 
400  
-You can set the `[api:i18n]` locale value which is used to format dates, currencies and other regionally different values to
  404
+You can set the `i18n` locale value which is used to format dates, currencies and other regionally different values to
401 405
 the same as your current page locale. 
402 406
 
403 407
 	:::php
@@ -414,7 +418,7 @@ the same as your current page locale.
414 418
 
415 419
 ### Adding a new locale
416 420
 
417  
-The `[api:i18n]` logic has lookup tables for common locales in i18n::$common_locales, which is a subset of i18n::$all_locales.
  421
+The `i18n` logic has lookup tables for common locales in i18n::$common_locales, which is a subset of i18n::$all_locales.
418 422
 If your locale is not present here, you can simply add it through `mysite/_config.php`:
419 423
 
420 424
 	:::php

0 notes on commit 1d7a84b

Please sign in to comment.
Something went wrong with that request. Please try again.